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. A live key can create, read, update, resolve, cancel, and report outcomes for Actions in its own Source and environment.

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. Native clients can send the bearer session token returned by sign-in:

curl -fsS "https://api.actionbox.cloud/v1/me/actions?status=open" \
  -H "Authorization: Bearer $ACTIONBOX_USER_TOKEN"

The browser uses the secure actionbox_session cookie instead. Check the current session with GET /v1/auth/session; revoke it with POST /v1/auth/logout. Signing out does not revoke Sources or other devices.

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 native challenge flows, and Sources and keys for the dashboard workflow.

Create, rotate, and revoke keys

POST /v1/sources creates a Source. The response returns the raw live token once. A user session can then rotate either key mode:

POST /v1/sources/{source_id}/keys/rotate
POST /v1/sources/{source_id}/keys/test/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. Keep live and test values in different configuration slots.
4. On 401, stop and inspect the credential boundary or rotate the key; do not keep retrying an invalid credential.
5. 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 Testing with sandbox keys.