Authentication
API keys
The kinds of key, which one goes where, and how to send it.
Every call to /v1 carries a key in the Authorization header:
curl "$SAPAGAN_URL/v1/customers/user-42" -H "Authorization: Bearer $SAPAGAN_KEY"A key looks like ktg_<kind>_<prefix>_<secret>. The prefix is 16 hex characters and the secret is 64. The kind in the key must match the key's stored kind. A key belongs to one workspace. Owners create and revoke keys in the console (Settings, Setup, API keys). The full key is shown once.
Key kinds#
| Kind | Starts with | Put it in | Can do |
|---|---|---|---|
| Server | ktg_workspace_ | Your backend only | Everything a workspace key may do on /v1: read and write people, consent, send, campaigns, journeys, settings. |
| Store | ktg_scope_ | A marketplace backend | Only one store's own data. See Stores. |
| App | ktg_app_ | Your app or web page | Register devices, identify, send events, report push opens, fetch in-app messages. Always needs an identity token. |
| Track | ktg_track_ | Older apps, and Customer.io-compatible backends | The same as App on /v1/batch. Also accepted on the /api/v1 and /api/v2 compatibility routes. |
| CDP | ktg_cdp_ | Reserved for Segment-style SDK traffic | Not usable on /v1. The /cdp/v1 routes are not live yet. |
Each reference page shows under "Accepted keys" which kinds may call an operation. A key of the wrong kind gets 403 credential_kind_not_allowed.
Store tokens#
A marketplace's seller portal does not hold one key per store. Sapagan verifies the seller's own session and returns a short-lived store token, which is sent as a Bearer token like a key. Store tokens last 15 minutes. The typed client takes a function so a rotating token needs no new client. See Server SDK.
Compatibility routes#
/api/v1 and /api/v2 take HTTP Basic with the key prefix as the user name and the secret as the password, as Customer.io's site id and API key do. Only Track keys are accepted there. See Migrating from Customer.io.
Failures#
| Answer | Meaning |
|---|---|
401 unauthorized | No key, or an unknown or revoked one. The answer carries WWW-Authenticate. |
403 credential_kind_not_allowed | The key is valid but its kind cannot use this route. |
403 store_blocked | A store key or token of a blocked store. |
403 organisation_suspended or workspace_archived | The organisation or workspace is switched off. |
404 not_found | The key's workspace or store cannot see this resource. The answer is the same whether it exists or not. |
An anonymous caller gets 401 even for a path that does not exist, so routes cannot be probed.
Rotating a key#
Create the new key, deploy it, watch "last used" on the old one, then revoke the old one (POST /v1/api-keys/{prefix}/revoke, owners in the console). A revoked key stays revoked.