Authentication
All API endpoints require Bearer token authentication.
Token Format
Authorization: Bearer htk_your_token_hereTokens start with the htk_ prefix followed by 64 hex characters.
Creating Tokens
Create tokens in Settings > API Tokens in the HPI dashboard. Each token needs:
- A descriptive name
- One or more scopes defining what the token can do
The full token value is shown once at creation — store it securely.
Scopes
| Scope | Permissions |
|---|---|
tasks:create | Create tasks, cancel tasks, upload files |
tasks:read | List and read task details |
processes:read | List and read process details |
processes:write | Create processes, push updates |
A token can have multiple scopes. Requests that require a scope the token doesn't have receive a 403 Forbidden response.
Organization Isolation
Tokens are bound to the organization that created them. All operations are automatically scoped to that organization:
- Tasks created with a token belong to the token's organization
- Listing tasks returns only the organization's tasks
- Process namespaces are prefixed with the organization ID
This isolation is enforced server-side — there's no way to access another organization's data.
Error Responses
| Status | Meaning |
|---|---|
401 Unauthorized | Missing or invalid token |
403 Forbidden | Token lacks the required scope |