API keys
API keys (pk_live_…) are what your backend uses to call poolse. Never
put one in a browser or mobile app. How keys and user tokens fit together:
Authentication.
Create a key
- Open API keys in the sidebar and click + Create API key.
- Fill in Create an API key:
- Name: up to 64 characters. Name it after where it runs, such as
productionorstaging. - Scopes: what the key may do.
users:manageis ticked for you.
- Name: up to 64 characters. Name it after where it runs, such as
- Click Create key. The Save this key now dialog shows the full key. Click Copy to clipboard, store it in your secret manager, then I've saved it — close.
Scopes can't be changed after creation. Create a new key instead.
Scopes
| Scope | Hint in the dashboard | Unlocks |
|---|---|---|
users:manage | mint user tokens | POST /v1/users/:user_id/tokens. Every integration needs this. |
tokens:admin | revoke user tokens | POST /admin/v1/tokens/revoke |
webhooks:admin | manage webhooks | Every /v1/webhooks* endpoint |
audit:read | read the audit log | GET /v1/audit_logs |
Every key, whatever its scopes, can call POST /v1/users,
GET /v1/whoami and the call history endpoints (GET /v1/calls,
GET /v1/calls/:id). A key without users:manage cannot mint user
tokens: that call returns 403 forbidden.
Give each deployment only the scopes it needs. An analytics job that
reads the audit log needs audit:read and nothing else.
The key list
Active keys shows, for each key:
| Column | Shows |
|---|---|
| Name | The name you gave it. |
| Prefix | The start of the key, so you can tell which key a service uses. |
| Scopes | Its scopes, or "none". |
| Last used | When it last authenticated a request, or "Never". |
| Created | When it was created. |
Revoked keys move to Revoked keys below, kept for reference.
Revoke a key
Click Revoke on the key's row, then Revoke again to confirm (or Cancel). The key is refused from its next request.
User tokens already minted with that key keep working until they expire,
at most one hour later. To cut one off sooner, revoke it with
POST /admin/v1/tokens/revoke (needs tokens:admin); see
Authentication.
Rotate a key
Create the new key, deploy it, then revoke the old one. Step by step: Token rotation.