Authentication

Overview

Activepieces API supports two authentication methods:

API Keys - Best for server-to-server integrations
JWT Tokens - Used for user sessions and authenticated requests

All authenticated requests must include credentials in the request headers.

API Keys

API keys are platform-scoped credentials for programmatic access to the Activepieces API.

Creating an API Key

API keys can be created via the platform dashboard or API:

Navigate to Platform Settings → API Keys
Click “Create API Key”
Provide a display name
Copy the generated key (starts with sk-)

API keys are shown only once during creation. Store them securely!

API Key Format

API keys follow this format:

sk-[64 random characters]

Example: sk-abc123def456...xyz789

Using API Keys

Include the API key in the Authorization header with the Bearer scheme:

curl https://cloud.activepieces.com/api/v1/flows \
  -H "Authorization: Bearer sk-your-api-key-here"

API Key Security

API keys are hashed using SHA-256 before storage
Only the last 4 characters are stored in plaintext for identification
Keys track lastUsedAt timestamp for auditing
Keys are scoped to a specific platform

Managing API Keys

List API Keys
Delete API Key

curl https://cloud.activepieces.com/api/v1/api-keys \
  -H "Authorization: Bearer sk-your-api-key-here"

Response:

{
  "data": [
    {
      "id": "key_123",
      "platformId": "platform_456",
      "displayName": "Production API Key",
      "truncatedValue": "...xyz9",
      "lastUsedAt": "2024-01-15T10:30:00.000Z",
      "created": "2024-01-01T00:00:00.000Z"
    }
  ],
  "next": null,
  "previous": null
}

curl -X DELETE https://cloud.activepieces.com/api/v1/api-keys/{keyId} \
  -H "Authorization: Bearer sk-your-api-key-here"

Response: 204 No Content

JWT Tokens

JWT (JSON Web Token) tokens are used for user authentication and session management.

Obtaining a JWT Token

Users can obtain JWT tokens through sign-in:

curl -X POST https://cloud.activepieces.com/api/v1/authentication/sign-in \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "your-password"
  }'

Response:

{
  "id": "user_123",
  "email": "user@example.com",
  "firstName": "John",
  "lastName": "Doe",
  "platformId": "platform_456",
  "projectId": "project_789",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "tokenVersion": 1
}

Using JWT Tokens

Include the JWT token in the Authorization header:

curl https://cloud.activepieces.com/api/v1/flows \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

JWT Token Structure

JWT tokens contain the principal information:

{
  "type": "USER",
  "id": "user_123",
  "projectId": "project_789",
  "platform": {
    "id": "platform_456"
  },
  "tokenVersion": 1,
  "exp": 1640000000
}

Token Expiration

Default expiration: 7 days
Engine tokens: 100 years (long-lived for flow execution)
Worker tokens: 100 years (for internal worker processes)

Token Versioning

Tokens include a tokenVersion to enable session invalidation:

Each user has a tokenVersion stored in their identity
When a token is verified, the version is checked
Incrementing the version invalidates all existing tokens
Useful for security events (password reset, logout all devices)

Authentication Headers

Required Headers

Header	Value	Description
`Authorization`	`Bearer <token>`	API key or JWT token
`Content-Type`	`application/json`	Required for POST/PUT requests

Optional Headers

Header	Description
`ap-parent-run-id`	Parent run ID for nested flow executions
`ap-fail-parent-on-failure`	Whether to fail parent run on child failure

Authentication Errors

Invalid Bearer Token (401)

{
  "statusCode": 401,
  "code": "INVALID_BEARER_TOKEN",
  "params": {
    "message": "invalid access token or session expired"
  }
}

Common causes:

Token is malformed or corrupted
Token signature verification failed
Token has expired

Session Expired (401)

{
  "statusCode": 401,
  "code": "SESSION_EXPIRED",
  "params": {
    "message": "The session has expired or the user is not verified."
  }
}

Common causes:

Token version mismatch (user logged out)
User account is inactive
User identity is not verified

Authorization Error (403)

{
  "statusCode": 403,
  "code": "AUTHORIZATION",
  "params": {}
}

Common causes:

Insufficient permissions for the requested operation
Attempting to access resources in a different project/platform

Security Best Practices

Secure API Key Storage

Store API keys in environment variables or secure vaults
Never commit API keys to version control
Rotate API keys periodically
Use different API keys for different environments

Token Handling

Store JWT tokens securely (e.g., HTTP-only cookies)
Implement token refresh logic before expiration
Clear tokens on logout
Validate token expiration on the client side

Network Security

Always use HTTPS in production
Implement IP allowlisting for sensitive operations
Monitor API key usage via lastUsedAt timestamps
Set up alerts for suspicious authentication patterns

Permission System

Activepieces uses a role-based permission system:

Principal Types

USER - Regular user with project-scoped permissions
SERVICE - API key with platform-scoped permissions
ENGINE - Internal engine execution context
WORKER - Internal worker process

Common Permissions

Permission	Description
`READ_FLOW`	View flows
`WRITE_FLOW`	Create/update flows
`UPDATE_FLOW_STATUS`	Enable/disable flows
`READ_RUN`	View flow runs
`WRITE_RUN`	Trigger/retry flow runs
`READ_APP_CONNECTION`	View connections
`WRITE_APP_CONNECTION`	Create/update connections
`WRITE_PROJECT`	Update project settings

Code Examples

import axios from 'axios';

const client = axios.create({
  baseURL: 'https://cloud.activepieces.com/api/v1',
  headers: {
    'Authorization': `Bearer ${process.env.ACTIVEPIECES_API_KEY}`,
    'Content-Type': 'application/json'
  }
});

// List flows
const response = await client.get('/flows', {
  params: { projectId: 'project_123' }
});

console.log(response.data);

import os
import requests

API_KEY = os.environ['ACTIVEPIECES_API_KEY']
BASE_URL = 'https://cloud.activepieces.com/api/v1'

headers = {
    'Authorization': f'Bearer {API_KEY}',
    'Content-Type': 'application/json'
}

# List flows
response = requests.get(
    f'{BASE_URL}/flows',
    headers=headers,
    params={'projectId': 'project_123'}
)

print(response.json())

package main

import (
    "fmt"
    "net/http"
    "os"
)

func main() {
    apiKey := os.Getenv("ACTIVEPIECES_API_KEY")
    baseURL := "https://cloud.activepieces.com/api/v1"
    
    client := &http.Client{}
    req, _ := http.NewRequest("GET", baseURL+"/flows?projectId=project_123", nil)
    req.Header.Add("Authorization", "Bearer "+apiKey)
    
    resp, _ := client.Do(req)
    defer resp.Body.Close()
    
    // Handle response
}

Overview

Endpoints

Overview

API Keys

Creating an API Key

API Key Format

Using API Keys

API Key Security

Managing API Keys

JWT Tokens

Obtaining a JWT Token

Using JWT Tokens

JWT Token Structure

Token Expiration

Token Versioning

Authentication Headers

Required Headers

Optional Headers

Authentication Errors

Invalid Bearer Token (401)

Session Expired (401)

Authorization Error (403)

Security Best Practices

Permission System

Principal Types

Common Permissions

Code Examples

Next Steps

Flows API

Projects API

​Overview

​API Keys

​Creating an API Key

​API Key Format

​Using API Keys

​API Key Security

​Managing API Keys

​JWT Tokens

​Obtaining a JWT Token

​Using JWT Tokens

​JWT Token Structure

​Token Expiration

​Token Versioning

​Authentication Headers

​Required Headers

​Optional Headers

​Authentication Errors

​Invalid Bearer Token (401)

​Session Expired (401)

​Authorization Error (403)

​Security Best Practices

​Permission System

​Principal Types

​Common Permissions

​Code Examples

​Next Steps

Flows API

Projects API

Overview

API Keys

Creating an API Key

API Key Format

Using API Keys

API Key Security

Managing API Keys

JWT Tokens

Obtaining a JWT Token

Using JWT Tokens

JWT Token Structure

Token Expiration

Token Versioning

Authentication Headers

Required Headers

Optional Headers

Authentication Errors

Invalid Bearer Token (401)

Session Expired (401)

Authorization Error (403)

Security Best Practices

Permission System

Principal Types

Common Permissions

Code Examples

Next Steps