Postal DevelopersAPI keys
Create a key, choose its scopes, rotate and revoke it.
Every request to api.postal.music/api/v1/* and every MCP connection is
authenticated with an API key that belongs to one Postal account. The key acts
as that account: it sees that account's library and nothing else.
Create a key
Sign in to Postal and open Settings → Integrations.
Click Create API key. The key is shown once; copy it somewhere safe. You can reveal it again later from the same screen.
Open Tools → Integration to narrow the key's scopes or attach a webhook URL. A key created from settings starts with every assignable scope and no expiry.
Keys look like an 8-character id, a dot, and a 32-character secret:
k7Qw2ZpL.Xj9c3vT1nR8mBq4sLw0yFh6dKe2aGu5pThe part before the dot identifies the key in logs and in the usage report. The part after it is never stored in plain text.
Send it
Put the key in the X-API-Key header:
curl https://api.postal.music/api/v1/tracks/count \
-H "X-API-Key: YOUR_API_KEY"Authorization: Bearer is reserved for the web app's session token and is not
accepted by the /api/v1 endpoints. The MCP server accepts either header.
Scopes
A key carries a list of scopes. Each endpoint declares the scope it needs, and
a key missing that scope gets 403 insufficient_scope.
| Scope | Grants |
|---|---|
read:tracks | List, get and count tracks; taxonomy; suggested tags; duplicates; submissions; natural-language search |
create:tracks | Upload tracks (multipart or by URL) |
update:tracks | Edit details and tags, trigger and apply auto-tagging, cover art |
read:playlists | List and get playlists |
create:playlists | Create playlists, add tracks |
update:playlists | Rename, remove tracks, reorder |
read:composers | List and count composers |
read:composer | Get a single composer |
create:composer | Create a composer |
update:composer | Update a composer |
delete:composer | Delete a composer |
read:analytics | Dashboard, per-entity stats, top tracks |
read:briefs | Briefs you own and their submissions |
read:shareholders | Reserved |
read_usage, create_key, revoke_key, rotate_key | Reserved for key management |
Two scopes you may see on older keys are not assignable: all is a legacy
wildcard that still works on the keys that have it, and act-as-user marks
service keys provisioned by Postal. platform:* scopes belong to
platform keys and are issued by Postal staff only.
Composer scopes come in pairs
Listing and counting composers needs read:composers; fetching one needs
read:composer. A key with only one of the two will half-work. Grant both.
Rotate and revoke
Both live in Tools → Integration. Rotating issues a new id and secret at once and invalidates the old pair; revoking disables the key permanently. Either action also disconnects any MCP client authorised with that key.
The same operations are exposed over HTTP for dashboard sessions; see Key management.
Good practice
- Create one key per integration so you can revoke one without touching the others.
- Grant only the scopes the integration uses. Read-only keys cannot change your library even if leaked.
- Keys have no expiry by default. Set
dayson creation if you want one. - Never ship a key in client-side code. The API is meant to be called from a server or a trusted desktop tool.