To authorize a public API request, send your API key in the Authorization header. The key identifies one app, and the request acts on that app.
Header
Authorization: Bearer <secret>- The scheme name
Beareris case-insensitive. - Whitespace around the header value and around the secret is ignored.
- A request without the header, or with another scheme, fails with
401 unauthenticated.
The secret and the key ID
An API key has two identifiers. Only the secret authenticates.
| Identifier | Format | Purpose | Authenticates |
|---|---|---|---|
| Secret | ppk_live_ followed by 64 hexadecimal characters | Sent in the Authorization header | Yes |
| Key ID | apk_ followed by 26 characters | Identifies the key in the console | No |
The console shows the secret once, when the key is created or rotated. After that it shows only the last 4 characters.
PayloadPuffin stores a hash of the secret, not the secret. A lost secret can't be read back. Rotating the key in the console issues a new secret for the same key ID. Rotate an API key describes the grace period for the replaced secret.
App scope
A key belongs to exactly one app. Operation paths contain no app ID, because the key selects the app. A key for one app can't read or change anything in another app, and an ID from another app returns 404 not_found.
Scopes
Each operation requires one scope. A key holds the scopes chosen when it was created, from this list:
events:writeevents:readdeliveries:readdeliveries:writedestinations:readdestinations:writesources:readsources:writeanalytics:read
The API overview lists the scope of each operation. API key scopes describes what each scope allows.
Expiry and deletion
A key has an expiry chosen when it is created: a time, or no expiry. From that time on, the secret fails with 401 unauthenticated, the same response as an unknown secret. A deleted key fails the same way. A change to a key's scopes or a deletion can take up to a minute to take effect.
Failure responses
| Status | code | detail | Cause |
|---|---|---|---|
401 | unauthenticated | Provide an API key as a Bearer token. | No Authorization header, or a scheme other than Bearer |
401 | unauthenticated | This API key doesn't exist, has expired or was deleted. Check the key, or create a new one in the console. | An unknown, expired or deleted secret, a key ID, or a replaced secret after its grace period |
403 | permission_denied | This API key requires the <scope> scope. | The key doesn't hold the scope the operation requires |
403 | permission_denied | Revealing a signing secret requires the destinations:write scope. | include=secret or include=previous_secret on GET /v1/destinations/{destinationId} without destinations:write |
Errors lists the order of checks.
The error body follows the format in Errors.