API Authentication

ActionBox has two authentication boundaries: user sessions for people and Source keys for software. Keep the boundaries separate so a browser session cannot become a machine credential and a worker cannot act as a dashboard user.

The hosted API base URL is:

https://api.actionbox.cloud

Choose a credential

Authenticate a machine request

Send the Source key as a Bearer token. It can create, read, update, resolve, cancel, and report outcomes for Actions in its own Source.

curl -fsS https://api.actionbox.cloud/v1/actions \
  -H "Authorization: Bearer $ACTIONBOX_SOURCE_KEY" \
  -H "Idempotency-Key: deploy-$BUILD_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Approve the production deploy",
    "options": [
      {"id": "approve", "label": "Approve", "style": "primary"},
      {"id": "reject", "label": "Reject", "style": "destructive"}
    ]
  }'

For machine-side reconciliation, use the Source-scoped read route:

curl -fsS "https://api.actionbox.cloud/v1/source/actions/$ACTION_ID?wait_seconds=30" \
  -H "Authorization: Bearer $ACTIONBOX_SOURCE_KEY"

wait_seconds is optional and is bounded to 30 seconds. It is a server wait, not a decision: if it returns while the Action is still open, read it again or continue your worker's normal reconciliation loop.

Source-authenticated controls are:

Authenticate a user request

User sessions are for the dashboard and user-scoped resources such as Sources, workspaces, notifications, and the inbox. The browser uses the secure actionbox_session cookie. Check the current session with GET /v1/auth/session; revoke it with POST /v1/auth/logout. Signing out does not revoke Sources.

Source management also requires a user session:

curl -fsS https://api.actionbox.cloud/v1/sources \
  -H "Authorization: Bearer $ACTIONBOX_USER_TOKEN"

See Authentication for provider sign-in, and Sources and keys for the dashboard workflow.

Create, rotate, and revoke keys

POST /v1/sources creates a Source. The response returns the raw token once. A user session can rotate it later:

POST /v1/sources/{source_id}/keys/rotate

The old key is revoked when the replacement is created, and the replacement is returned only once. DELETE /v1/sources/{source_id} revokes the Source and all active keys while preserving its Actions, events, and webhook history. List and detail responses expose safe key metadata, never raw tokens.

If a callback is configured, rotate its separate signing secret with:

POST /v1/sources/{source_id}/webhook-secret/rotate

The raw secret is also returned once. It is not interchangeable with a Source key; see Webhooks and callbacks.

Authentication checklist

1. Select the credential class before choosing the route: user session for workspace resources, Source key for machine resources.
2. Store the raw value in the process's secret store and inject it at runtime.
3. On 401, stop and inspect the credential boundary or rotate the key; do not keep retrying an invalid credential.
4. On an uncertain write, preserve the same idempotency key and retry only the same logical request. See Idempotency and safe retries.

Next: Creating Actions, Errors and retries, or Deploying an integration.