Service tokens

Endpoint: /api/auth/service-tokens/

Issue a service token for an application to run automation within that application’s roles and the token’s access-control rules. Its key starts with alpst-. A service token cannot call the users API or the applications API.

Authentication and permissions#

Token management and history require a person signed in to the console or CLI. Create also accepts the caller’s own personal API token with service_token:create. Other management actions refuse personal API tokens; all management actions refuse service tokens with 403 permission_denied.

The examples with Authorization: Bearer <access_token> use a signed-in session. These routes require that session except create, which also accepts your own personal API token with service_token:create using the token authorization format. No service token can call them. Follow the setup guide to create and approve a token. A service token created from the CLI always waits for approval in the web console. See API authentication.

An admin can read, create, update, rotate, disable and delete tokens. The application’s creator receives the application:maintainer role for it: they can read, create and update its tokens, but need an additional grant to rotate, disable or delete them. The service_token:manager role also grants read, create and update, globally or for an application. Break-glass is Superuser-only, even for an admin.

Writes are refused with 403 workspace_suspended while the workspace is suspended, except for activating or deactivating break-glass.

List tokens#

Request#

GET /api/auth/service-tokens/tokens/

Only tokens for applications on which you have service_token:read appear.

Query parameters#

Use activation_state=active&enabled=false to find switched-off tokens, and activation_state=pending for tokens awaiting approval.

Response#

200 OK, using integer pagination:

{
  "count": 1,
  "current": 1,
  "next": null,
  "previous": null,
  "last": 1,
  "results": [
    {
      "id": "3f1c2a9e-7b6d-4e1f-9a2b-5c8d7e6f4a31",
      "name": "ci-deploy",
      "activation_state": "active",
      "enabled": true,
      "scopes": ["command:create", "command:read"],
      "expires_at": "2027-01-01T00:00:00Z"
    }
  ]
}

The example shows selected token fields. The next section lists the full set.

Example#

curl "https://your-workspace.us1.alpacon.io/api/auth/service-tokens/tokens/?activation_state=pending" \
  -H "Authorization: Bearer <access_token>"

Token fields#

Create a token#

Request#

POST /api/auth/service-tokens/tokens/

The scopes must fit the application’s global roles, including when a Superuser creates the token. Presets are merged with explicit scopes; unavailable scopes are removed from presets. The resulting set cannot be empty. Explicitly requesting an unmintable scope returns 400 service_token_scope_not_mintable.

Service tokens cannot receive ftp_session:create, session:create, session:invite, session:share, tunnel_session:create, tunnel_session:reconnect, userchannel:create or userchannel:update. Cluster scopes are also refused when the workspace does not offer Kubernetes access.

Request body#

{
  "name": "ci-deploy",
  "application": "9d2e4b71-0c3a-4f5e-8b6d-1a2c3e4f5a6b",
  "scopes": ["command:create", "command:read"],
  "expires_at": "2027-01-01T00:00:00Z",
  "rotation_policy": "90d",
  "justification": "Run deployment checks from CI"
}

Response#

The token and its key are created in both cases:

Any wildcard is high risk. Command, upload, download and session scopes with an access-control requirement are medium risk. Other scopes are low risk. A token with command scopes always returns 202 and requires justification, including when a signed-in admin creates it in the web console.

A 202 returns the full token, including key, and adds status, risk_level, risk_details and approval_request_id. Selected fields:

{
  "id": "3f1c2a9e-7b6d-4e1f-9a2b-5c8d7e6f4a31",
  "key": "alpst-xxxxxxxxxxxxxxxxxx",
  "activation_state": "pending",
  "enabled": false,
  "status": "pending_approval",
  "risk_level": "medium",
  "risk_details": [],
  "approval_request_id": "5cf4106b-b6c5-4ae3-b33c-e90e7a872155"
}

risk_details contains entries shaped as {scope, reason, level}; the array above omits those entries for brevity. Save the key from this response: the approver does not receive it. A pending token authenticates nowhere until approval. The approval request expires after 7 days.

A Superuser or an approver assigned to the request approves it in the web console; CLI and token calls cannot approve. The requester may approve their own request unless an approval-policy rule forbids it. Approval rechecks the application’s roles and the expiry time. Rejection, cancellation or expiry invalidates the pending key.

After approval, GET /api/auth/service-tokens/tokens/{id}/ returns 200 with activation_state: "active" and enabled: true. Only then can you add ACLs: ACL writes require an enabled, approved service token.

Example#

curl -X POST "https://your-workspace.us1.alpacon.io/api/auth/service-tokens/tokens/" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{"name":"ci-deploy","application":"9d2e4b71-0c3a-4f5e-8b6d-1a2c3e4f5a6b","scopes":["command:create","command:read"],"expires_at":"2027-01-01T00:00:00Z","justification":"Run deployment checks from CI"}'

Get a token#

GET /api/auth/service-tokens/tokens/{id}/

id is the token UUID. Returns 200 with the token fields and scope_usage, but no key. Read activation_state and enabled to check whether a pending token has been activated.

Update a token#

Request#

PATCH /api/auth/service-tokens/tokens/{id}/
PUT /api/auth/service-tokens/tokens/{id}/

name and description changes apply immediately. A request touching any of these sensitive fields returns 202 and waits for approval, for every caller:

• scopes, enabled, expires_at, rotation_policy
• ip_whitelist, rate_limit
• allowed_time_start, allowed_time_end, allowed_days

This includes PATCH {"enabled": false}. Use Disable a token to stop use immediately. There is no enable route: request PATCH {"enabled": true} and wait for approval. The application’s roles are checked again when re-enabling a token.

Only one modification may be pending per token. A token still awaiting its initial approval cannot be updated. application is read-only: create a new token to use a different application. presets are refused on update.

PUT also supplies defaults for ip_whitelist, rate_limit and allowed_days, so it returns 202. Prefer PATCH when changing selected fields.

Response#

An immediate update returns 200 with the token and no key. A sensitive update returns:

{
  "status": "pending_approval",
  "risk_level": "medium",
  "risk_details": [],
  "approval_request_id": "5cf4106b-b6c5-4ae3-b33c-e90e7a872155"
}

This body contains no key. risk_details uses {scope, reason, level} entries, omitted above for brevity. Scope changes must fit the application’s roles both when requested and when approved.

Example#

curl -X PATCH "https://your-workspace.us1.alpacon.io/api/auth/service-tokens/tokens/3f1c2a9e-7b6d-4e1f-9a2b-5c8d7e6f4a31/" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{"rate_limit":"2000/hour","justification":"Support deployment checks across more servers"}'

Rotate a key#

POST /api/auth/service-tokens/tokens/{id}/rotate/

Send an optional reason string of at most 1,024 characters. Rotation needs no approval, but your own global roles must cover the token’s stored scopes. Pending and disabled tokens cannot be rotated.

Returns 200 with the token and its new key. The old key stops authenticating immediately, with no overlap. Expiry resets to now plus rotation_policy, not the old expiry plus that duration; this can make the lifetime shorter. Update the secret in the automation that uses it in the same step.

curl -X POST "https://your-workspace.us1.alpacon.io/api/auth/service-tokens/tokens/3f1c2a9e-7b6d-4e1f-9a2b-5c8d7e6f4a31/rotate/" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{"reason":"Scheduled key rotation"}'

Disable a token#

POST /api/auth/service-tokens/tokens/{id}/disable/

Send an optional reason string of at most 1,024 characters. Returns 204 No Content and stops the token immediately without approval. It also ends all active break-glass access for the token. Pending tokens cannot be disabled.

A token is also disabled if an application role or permission is removed and its stored scopes exceed the application’s remaining permissions.

Delete a token#

DELETE /api/auth/service-tokens/tokens/{id}/

Send an optional reason string of at most 1,024 characters. Returns 204 No Content; the token stops authenticating. Deleting a pending token also cancels its issuance request and invalidates its key. Its history remains available while the application exists.

Break-glass#

Break-glass temporarily lifts only the IP whitelist, allowed hours and allowed days. The token must still be approved and enabled, with a valid, unexpired key. It cannot authenticate if its application has been deleted. Rate limits, scopes, application roles and ACLs still apply. See Access-control lists.

Activate#

POST /api/auth/service-tokens/tokens/{id}/break-glass/

Only a signed-in Superuser can activate break-glass, including while the workspace is suspended.

{
  "justification": "Restore deployment access during the incident",
  "duration_hours": 2
}

Returns 201 with {id, service_token, activated_by, justification, activated_at, expires_at, deactivated_at, is_active}. A pending token is refused. Activating break-glass does not make a disabled or expired token usable. The exception remains effective only while the activating user is active and a Superuser; deactivation or demotion ends it.

Deactivate#

DELETE /api/auth/service-tokens/tokens/{id}/break-glass/

Only a signed-in Superuser can deactivate it. Returns 204 and ends all active break-glass access for this token. If none is active, returns 400 service_token_break_glass_not_active. Activation and deactivation are recorded in history and send webhooks.

Token history#

Request#

GET /api/auth/service-tokens/history/?service_token={token_id}
GET /api/auth/service-tokens/history/{history_id}/

Both routes require service_token:read on the application. The list also requires the service_token query parameter: a missing parameter returns 400 service_token_history_scope_required, and an invalid or inaccessible token ID returns 404 api_not_found. Detail uses the history entry UUID without requiring that query parameter.

Query parameters#

Change types are created, activated, updated, rotated, disabled, deleted, break_glass_activated and break_glass_deactivated.

Response#

The list returns 200 with count, current, next, previous, last and results. Detail returns one history entry:

{
  "id": "660e8400-e29b-41d4-a716-446655440000",
  "service_token_id": "3f1c2a9e-7b6d-4e1f-9a2b-5c8d7e6f4a31",
  "service_token_name": "ci-deploy",
  "change_type": "updated",
  "changed_by": null,
  "changes": {"description": {"old": "", "new": "Deployment checks"}},
  "reason": "Clarify the token's purpose",
  "added_at": "2026-10-24T10:00:00Z"
}

Keys are masked as ***. History remains readable after token deletion, but not after application deletion.

Read-only helpers#

These routes help you choose scopes, presets and servers before creating a token or its ACLs. They require authentication. The scope and server helpers also require permission to create tokens for the requested application; a personal token reading the server helper needs server:read.

Missing application returns 400 service_token_application_required. An invalid, unknown or deleted application returns 404 api_not_found; lacking permission to create tokens for it returns 403 service_token_application_forbidden.

Error responses#

When using the issued alpst- key, invalid, disabled, pending, expired or deleted tokens, including tokens on deleted applications, return 401 auth_authentication_failed. IP and time restrictions return 401 auth_ip_not_allowed or auth_access_outside_allowed_time. Exceeding the token’s rate limit returns 429 api_rate_limited with Retry-After; inability to verify a credential returns 503 auth_verification_unavailable. See API authentication.