Postal DevelopersKey management
Create, scope, rotate and revoke keys, and read usage, from a dashboard session.
These endpoints manage API keys. They are authenticated with the web app's session token, not with an API key, because a key must never be able to mint or widen another key. Most integrations never call them; the app's Settings → Integrations and Tools → Integration screens cover the same operations.
Base path: https://api.postal.music/integration. Send
Authorization: Bearer <session token>.
Create a key
POST /integration/api-keys{ "name": "Catalogue sync", "scopes": ["read:tracks", "create:tracks"], "days": 365 }| Field | Type | Notes |
|---|---|---|
name | string | Required |
scopes | string[] | Any of the assignable scopes. Omit for all of them |
days | integer ≥ 1 | Expiry. Omit for no expiry |
Returns { "key": "k7Qw2ZpL.Xj9c…", "id": "k7Qw2ZpL" }. The key is shown only
here.
Current key
GET /integration/api-keysReturns the newest non-revoked key: id, name, scopes, webhookUrl,
webhookActive, createdAt, lastUsedAt, expiresAt, and the raw key.
Scope catalog
GET /integration/api-keys/scopesReturns { "scopes": [ … ] }, the assignable list.
Replace scopes
POST /integration/api-keys/{id}/scopesBody { "scopes": [ … ] }. Unknown scopes return 400 invalid_scope. Keys
carrying act-as-user or a platform:* scope cannot be edited.
Set webhook
POST /integration/api-keys/{id}/webhookBody { "url": "https://…", "active": true }. See Webhooks.
Rotate
POST /integration/api-keys/{id}/rotateIssues a new id and secret and invalidates the old ones. Returns
{ "id", "createdAt", "key" }. Scopes and webhook settings carry over.
Revoke
POST /integration/api-keys/{id}/revokePermanent. Returns { "ok": true }.
Usage
GET /integration/usage?limit=50&cursor=…&from=2026-09-01&to=2026-09-07Every request made with your keys: route, method, status, duration, IP and
timestamp. Cursor-paginated with items and nextCursor.