Authentication

All API requests must be authenticated. apptor flow supports two authentication methods.

---

API Key (Recommended for integrations)

API Keys are the primary method for machine-to-machine access. They are scoped to an organization and carry RBAC permissions via assigned roles.

Format

apk_{keyId}_{secret}

Request Header

X-API-Key: apk_key123abc_secretxyz789...

Example

curl -X POST https://your-domain.com/process/exec \
  -H "Content-Type: application/json" \
  -H "X-API-Key: apk_key123abc_secretxyz789" \
  -d '{"processId": "workflow-001", "data": {"customerName": "Jane"}}'

API Key Properties

Property	Description
keyId	Public identifier (visible in UI)
secret	Secret part (shown only at creation)
status	ACTIVE, SUSPENDED, or REVOKED
rateLimitPerMinute	Max requests per minute (null = unlimited)
rateLimitPerHour	Max requests per hour (null = unlimited)
expiresAt	Expiry timestamp (null = never expires)

Rate Limiting

When a rate limit is exceeded, the API returns:

HTTP/1.1 429 Too Many Requests
Content-Type: application/json

{
  "error": "RATE_LIMIT_EXCEEDED",
  "message": "API key rate limit exceeded. Retry after 60 seconds.",
  "retryAfter": 60
}

---

Bearer JWT (Browser / OIDC)

Used by the Angular frontend after OIDC authentication.

Request Header

Authorization: Bearer eyJhbGciOiJSUzI1NiJ9...

OIDC Flow

1. Frontend redirects to OIDC provider login
2. Provider redirects to /auth/callback?code=...
3. Frontend exchanges code for JWT access token
4. All subsequent requests include Authorization: Bearer {token}

---

Which Method to Use

Use Case	Method
Server-to-server API calls	API Key (X-API-Key)
Trigger workflows from external systems	API Key
CI/CD pipeline integrations	API Key
Browser UI (Angular app)	JWT (Authorization: Bearer)
Webhook-triggered workflows	API Key

---

Endpoints Accepting Anonymous Access

Some endpoints accept requests without authentication (with SecurityRule.IS_ANONYMOUS):

• GET /process/list — requires WORKFLOW_READ permission via API Key, or returns public workflows
• POST /process/start — triggers a workflow (requires WORKFLOW_EXECUTE on the API Key)
• POST /process/exec — triggers a workflow
• GET /process/{id}/instances — lists executions
• GET /process/instance/{instanceId} — gets execution status
• GET /process/instance/{instanceId}/logs — streams execution logs (SSE)
• POST /process/task — completes a user task

These endpoints still enforce permission checks on API Keys. Unauthenticated requests to these endpoints return HTTP 401.

---

Error Responses

HTTP Status	Meaning
401 Unauthorized	No credentials provided or credentials are invalid
403 Forbidden	Valid credentials but insufficient permissions
429 Too Many Requests	Rate limit exceeded

{
  "error": "UNAUTHORIZED",
  "message": "Invalid or missing API key",
  "timestamp": "2026-02-20T10:00:00Z"
}

---

Managing API Keys

API Keys are managed via the API Keys API or through the admin UI at /admin/api-keys.