Your application talks to the public API with an API key. The key decides which app a request acts on and what the request may do there. You never send an app ID.
Authorization: Bearer ppk_live_...One key, one app
A key belongs to the app it was created in. Every request made with it reads and writes that app's data only, so a staging key can't send events to production. Give each environment its own app and its own keys.
Owners and admins create and manage keys on the console's API Keys page. A key can't create or manage other keys, and the public API has no operation for it. Create an API key walks through the form.
What a key is made of
| Part | Example | Purpose |
|---|---|---|
| Secret | ppk_live_... | The Bearer token. Shown once, when the key is created or rotated |
| Key ID | apk_... | Identifies the key in the console. It can't authenticate |
| Name | billing-service | Says what the key is for |
| Scopes | events:write | What the key may do. See API key scopes |
| Expiry | 30 days, or never | When the key stops working |
PayloadPuffin stores a SHA-256 hash of the secret, not the secret itself. The console shows only its last four characters. Nobody can show you a lost secret again, including us. Rotate the key instead.
Expiry
You choose an expiry when you create the key: a date, or no expiry at all. The console suggests 30 days. From the expiry on, requests with the key fail with 401. You can move an expiry earlier later, but never later or back to no expiry. Expired keys move to the Inactive tab.
Give every key an expiry. A key that never expires is a key nobody remembers to replace.
Scopes
A key holds one or more of nine scopes. Events, deliveries, destinations and sources each have read and write scopes. Analytics has a read scope. See API key scopes for the operations each allows. A request that needs a scope the key lacks fails with 403, and the response names the missing scope.
Give each integration only the scopes it uses. A service that only sends events needs events:write and nothing else.
Rotation and deletion
Rotating a key replaces its secret and keeps its ID, name, scopes and expiry. The old secret can keep working for a grace period you choose, from none up to seven days, so you can deploy the new one first. A key has at most two working secrets at a time. Rotate an API key has the steps.
Deleting a key stops both of its secrets. The key stays listed under Inactive with its last use, and you can't undo the deletion.
A change to an existing key, such as new scopes, a revoked secret or a deletion, can take up to a minute to take effect.
Last used
The console shows when each key was last used. It updates at most once an hour, and it records use of the key, not of one particular secret. A rotated key's old and new secrets count as the same key.