Every API request is authenticated with an API key sent as a bearer token.
curl https://api-prod.getpocketpass.com/api/v1/passes \
-H "Authorization: Bearer pk_live_your_key_here"
Creating a key
Open Settings → API keys, choose a name, and create.
Name keys after where they're used, not who created them - "Checkout service", "Booking system", "Staging". When you come to revoke one, that's the information you'll want.
The key is displayed once, immediately after creation. It cannot be retrieved afterwards - we store only a hash, so we genuinely can't show it to you again.
Copy it into your secret store before leaving the page. If you lose it, revoke it and create another.
What a key can do
A key acts on behalf of the account it was created in, with full read and write access to that account's templates, passes, notifications and webhook subscriptions.
It is not tied to the person who created it. Removing someone from your team does not revoke keys they created - see Team members and roles.
Keys are scoped to one account. A key from one account returns nothing for another. See Working across multiple accounts.
Keeping keys safe
A PocketPass key can issue passes, change passes people are holding and message every one of your customers. Treat it like a production database credential.
- Server-side only. Never in a browser, a mobile app, or anything a user can view source on.
- Never in git. Environment variables or a secret manager.
- One key per system. If a key leaks, you revoke one integration rather than all of them.
- Separate keys per environment, so staging can't touch production data.
If a key has ever been committed to a repository, pasted into a chat, or logged - revoke it. Rotating is a few minutes' work; a compromised key can message your entire customer base.
Rotating without downtime
Because keys are independent, rotation needs no maintenance window:
- Create a new key.
- Deploy it to the system that needs it.
- Confirm the system is working on the new key.
- Revoke the old one.
Both keys work during the overlap. Rotate on a schedule, and whenever someone with access leaves.
Revoking
Revoke from the API keys list. It takes effect immediately, and every request using that key starts getting 401.
Revoking cannot be undone. There's no un-revoke - you create a new key instead. Make sure you're revoking the right one; the list shows each key's prefix and last four characters to help you match it against your config.
Revoking a key does not affect passes it created. They carry on working normally.
What the errors mean
| Status | Code | Means |
|---|---|---|
401 | unauthorized | Missing, malformed, unknown or revoked key. Check the header format and that the key hasn't been revoked. |
403 | forbidden | Valid key, but not allowed to do this. |
403 | account_suspended | The account itself is suspended. Get in touch. |
429 | rate_limited | Too many requests. See API errors and rate limits. |
A common cause of 401 in a first integration is the header format. It must be exactly Authorization: Bearer <key> - the word Bearer, a single space, then the key.
Where to go next
- API quickstart.
- API errors and rate limits.
- Webhooks - which use their own signing secret, separate from API keys.