SapaganDocs sapagan.com

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#

KindStarts withPut it inCan do
Serverktg_workspace_Your backend onlyEverything a workspace key may do on /v1: read and write people, consent, send, campaigns, journeys, settings.
Storektg_scope_A marketplace backendOnly one store's own data. See Stores.
Appktg_app_Your app or web pageRegister devices, identify, send events, report push opens, fetch in-app messages. Always needs an identity token.
Trackktg_track_Older apps, and Customer.io-compatible backendsThe same as App on /v1/batch. Also accepted on the /api/v1 and /api/v2 compatibility routes.
CDPktg_cdp_Reserved for Segment-style SDK trafficNot 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#

AnswerMeaning
401 unauthorizedNo key, or an unknown or revoked one. The answer carries WWW-Authenticate.
403 credential_kind_not_allowedThe key is valid but its kind cannot use this route.
403 store_blockedA store key or token of a blocked store.
403 organisation_suspended or workspace_archivedThe organisation or workspace is switched off.
404 not_foundThe 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.