Skip to main content

​
Overview

Activepieces API supports two authentication methods:
  1. API Keys - Best for server-to-server integrations
  2. 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:
  1. Navigate to Platform Settings → API Keys
  2. Click “Create API Key”
  3. Provide a display name
  4. 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

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
}

​
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

HeaderValueDescription
AuthorizationBearer <token>API key or JWT token
Content-Typeapplication/jsonRequired for POST/PUT requests

​
Optional Headers

HeaderDescription
ap-parent-run-idParent run ID for nested flow executions
ap-fail-parent-on-failureWhether 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

  • 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
  • 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
  • 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

PermissionDescription
READ_FLOWView flows
WRITE_FLOWCreate/update flows
UPDATE_FLOW_STATUSEnable/disable flows
READ_RUNView flow runs
WRITE_RUNTrigger/retry flow runs
READ_APP_CONNECTIONView connections
WRITE_APP_CONNECTIONCreate/update connections
WRITE_PROJECTUpdate 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);

​
Next Steps

Flows API

Start creating and managing flows

Projects API

Manage projects and team settings