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. User tags require users:read, users:write or users:delete for reading, merging or deleting a profile. New secret keys include these scopes. Existing active keys with the full server scope set receive them automatically when the feature is deployed. Restricted keys keep their explicit permissions.

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.

Separate development and production devices

We recommend creating two Carillon apps: one for development and one for production. Each app keeps its devices, audiences, campaigns and API keys separate. Configure each build with the mobile key of its corresponding app, and use that app's secret key in the backend that sends its notifications.

Use live Carillon keys in the development app to receive real notifications. Test keys simulate delivery and do not send notifications to a device. An APNs sandbox build also uses live Carillon keys. Use separate native bundle/package identifiers when development and production builds must coexist on a device.

Upload provider credentials to each app. You can reuse the original credential file when its provider scope permits it; for APNs, configure the correct Bundle ID for each app. Store the original .p8 securely: Apple allows it to be downloaded only once, and Carillon does not export uploaded credentials.

After configuring the development build, check that its device appears in the development app's Devices list, then send a notification from that app. Changing a mobile key does not remove the device's registration from the old app. See provider credentials and registration troubleshooting.