Skip to content
PayloadPuffin.
Join the waitlist

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.

TEXT
Authorization: Bearer <secret>
  • The scheme name Bearer is 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.

IdentifierFormatPurposeAuthenticates
Secretppk_live_ followed by 64 hexadecimal charactersSent in the Authorization headerYes
Key IDapk_ followed by 26 charactersIdentifies the key in the consoleNo

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:write
  • events:read
  • deliveries:read
  • deliveries:write
  • destinations:read
  • destinations:write
  • sources:read
  • sources:write
  • analytics: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

StatuscodedetailCause
401unauthenticatedProvide an API key as a Bearer token.No Authorization header, or a scheme other than Bearer
401unauthenticatedThis 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
403permission_deniedThis API key requires the <scope> scope.The key doesn't hold the scope the operation requires
403permission_deniedRevealing 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.