Authentication
Every call carries the key in the Authorization header. No header, malformed header or unknown key: 401.
bash
curl "https://public-api.passkey.global/v1/sales" \
-H "Authorization: Bearer passkey_prd_SEU_SEGREDO_AQUI"Getting a key
- The key comes from the API keys section under Settings — the screen generates it.
- The secret is shown once. Store it right away — we keep only its hash, so there is no "show again". If you lose it, revoke and generate another.
You can hold 2 active keys at once. Two on purpose: it is what lets you rotate in production with no gap — create the new one, switch your system over, revoke the old one.
Key lifetime
When you create a key you choose how long it lasts: 1 day, 30 days, 90 days or permanent. The choice is made once and cannot be changed afterwards — to change the term, create another key and revoke this one.
- 1, 30 or 90 days — the key stops working on that date and starts returning
401API_KEY_EXPIRED. The expiry date is shown in the key list. - Permanent — no expiry date. It only stops when you revoke it.
Permanent is not forever: a key unused for more than 90 days is revoked automatically. A key never used counts from its creation date. If your integration calls the API regularly, this never reaches you.
Scopes
A key carries scopes, and each endpoint requires its own. An authenticated key without the required scope returns 403, not 401 — the difference matters, because 401 asks for a different credential and 403 for a different permission.
| Scope | Grants |
|---|---|
tracking:read | the three /v1 read endpoints |
tracking:write | reserved; no public endpoint uses it today |
When a key stops working
| Situation | Response |
|---|---|
| Key revoked in the dashboard | 401 API_KEY_REVOKED |
| Key expired | 401 API_KEY_EXPIRED |
| Account blocked, delinquent or removed | 401 / 403, depending on the case |
| Insufficient scope | 403 API_KEY_SCOPE_DENIED |
Revoking takes effect immediately: there is no permission cache between the revocation and the next call.
Handling the key
- The key identifies the whole account. Treat it like a password: environment variable or vault, never in source, never in a repository.
- It grants read access to your sales history. Do not use it in a frontend — any visitor could read the header.
- Suspect a leak: revoke it in the dashboard. The key dies immediately and the rest of the account is untouched.
The limit is 120 requests per minute, per key. The counter is per key, not per IP.