Authentication

Choose the right ActionBox credential for people, browsers, native clients, and machine integrations.

ActionBox has two authentication boundaries: user sessions for people and Source keys for software. Keeping them separate limits what a browser, teammate, or automation can see and change.

User session

Dashboard and user-scoped API calls use a secure session cookie or an axb_usr_ bearer token.

Source key

Machine calls use one Source-scoped axb_live_ or axb_test_ key in an Authorization header.

Provider identity

Google and Apple sign-in are verified server-side before a user session is created.

Choose a credential

Caller	Credential	Typical calls
Browser dashboard	`actionbox_session` HttpOnly cookie	`/v1/bootstrap`, `/v1/me/actions`, Sources, workspaces, notifications
Native client	`axb_usr_…` bearer session token	User-scoped actions, devices, and workspace APIs
Script, worker, CI job, or agent	`axb_live_…` Source key	Create, update, resolve, cancel, and report outcomes for that Source
Isolated test process	`axb_test_…` Source key	Create test Actions without mixing them into the live inbox or quota

Never swap the boundaries

A Source key is not a dashboard login, and a user session is not a machine identity. Keep Source keys out of browser bundles, URLs, logs, screenshots, and source control.

The dashboard can use the sign-in methods that are enabled for your ActionBox account. The provider list is public, so a client can discover which methods are available:

curl https://api.actionbox.cloud/v1/auth/providers

The browser flow is:

1. Start the provider flow

Open the provider start route with a local destination such as /actions:

GET /v1/auth/google/start?next=/actions

ActionBox creates a short-lived signed state cookie and an OAuth nonce before redirecting to the provider.

Google or Apple returns to the exact configured callback. ActionBox verifies the signed state, nonce, provider token signature, issuer, audience, expiry, and verified email before linking or creating the user.

3. Continue to the dashboard

ActionBox sets the secure, HttpOnly actionbox_session cookie and redirects only to a validated local next path. Check the current session with:

curl -b 'actionbox_session=<browser-cookie>' \
  https://api.actionbox.cloud/v1/auth/session

Sign-in availability and account access rules depend on your ActionBox account. Check /v1/auth/providers before presenting a sign-in option; do not assume that every provider is available.

Native clients use a one-time server challenge so the provider identity is bound to a fresh nonce.

Google

POST /v1/auth/google/native/challenge

{
  "data": {
    "challenge_id": "ngc_…",
    "nonce": "…",
    "expires_in": 300
  }
}

Pass the nonce to the native Google SDK, then exchange the returned ID token:

POST /v1/auth/google/native
Content-Type: application/json

{
  "challenge_id": "ngc_…",
  "id_token": "<Google ID token>"
}

The challenge expires after five minutes and accepts one verification attempt. The server verifies the token signature, issuer, audience, expiry, verified email, and nonce before returning an axb_usr_… session token.

Apple

iOS follows the same challenge contract at POST /v1/auth/apple/native. Android uses the Apple Services ID browser flow, returns through the ActionBox deep-link relay, and exchanges the one-time authorization code at POST /v1/auth/apple/android.

Use a user session

Native clients send the returned user token as a Bearer token:

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

The session can be checked with GET /v1/auth/session and revoked with POST /v1/auth/logout. Sessions expire and can be revoked independently; signing out does not revoke Sources or other devices.

Sign out safely

Call POST /v1/auth/logout for the current user session.
Revoke a device from Devices if it is no longer trusted.
Rotate or revoke a Source separately if its machine credential may have leaked.

Next: Create a Source for your first machine integration, or return to the Getting Started guide.

Authentication

User session

Source key

Provider identity

On this page