Authentication

Send credentials in the Authorization: Bearer <value> header to https://api.carillon.dev.

Choose a credential

API keys belong to one app. They cannot access another app's devices or campaigns. Management endpoints under /v1/organizations/… and /v1/apps/… require a session token, except audience endpoints, which also accept scoped secret keys from that app. Audience list/preview requires audiences:read; creation/deletion requires audiences:write. New secret keys include these scopes. Existing keys keep their original scopes.

Create API keys

Open your app's API keys page in the dashboard, or use carillon key create. Each new app already has one mobile key. In the creation dialog, select Live for real sends or Test for simulated delivery. Both mobile and secret keys support test mode.

Test mode

The mode is carried by the key prefix and by nothing else: no request parameter switches it.

A test send is accepted, resolved, paced and traced like a live one; only the network call to Apple or Google is replaced, so no notification reaches a phone. Test sends and test devices count toward neither usage nor billing.

Devices registered with a test mobile key and campaigns sent with a test secret key are kept apart from live ones: a test secret key cannot target a live device, even by ID. Test registration accepts magic tokens that drive a chosen simulated outcome; live registration refuses them.

Test mode does not verify rendering. To see a real notification on a real device before going live, use a dedicated app with its own provider credentials and live keys; an APNs sandbox credential is a real provider integration, not test mode. See going live.

• Mobile keys stay readable in the dashboard and GET /v1/apps/{appId}/keys. They are intended to ship in the app binary.
• Secret keys are shown once when created. Store them in your backend's secret configuration. A lost secret key must be replaced.

Both key prefixes are followed by 43 base64url characters. Never put a secret key in a mobile app. A mobile key cannot send notifications or read delivery results; those requests return 403.

curl https://api.carillon.dev/v1/messages/01937b20-0000-7000-8000-000000000000 \-H "Authorization: Bearer carillon_sk_live_your_secret_key"

Rotating keys

Secret key

1. Create a new secret key.
2. Deploy it to every backend using the old key.
3. Revoke the old key.

Mobile key

1. Create a new mobile key and include it in an app release.
2. Keep the old key active while you support installed versions that use it.
3. Revoke it when those versions no longer need to register devices or report events.

An app can have several active mobile keys. Revocation takes effect immediately: installed versions using the revoked key cannot register or report events until they update to a version with an active key.

The management session

Run carillon login to authorize the CLI through your browser. A session token authenticates management API requests:

curl https://api.carillon.dev/v1/apps/your_app_id/keys \-H "Authorization: Bearer YOUR_SESSION_TOKEN"

The MCP server uses OAuth to authorize an agent with your organization memberships.

Authentication errors

Failures use the Problem Details error format.