Postal DevelopersAuth and scopes
How the MCP server authenticates, and which scopes a key needs for which tools.
Two ways in
OAuth 2.1 (connectors). Claude and other connector-style clients discover
the server at /.well-known/oauth-authorization-server, register
dynamically, and send you to an authorisation page where you paste a Postal
API key. The key is exchanged for a one-hour access token with a 30-day
refresh token. The client never holds the key.
Direct header. Clients that let you set headers can send the key on every
request as X-API-Key: <key> or Authorization: Bearer <key>. No token
exchange.
Either way, every tool call becomes REST API calls made with that key, so the key's scopes apply.
Scope per tool
| Scope | Tools |
|---|---|
read:tracks | list_tracks, get_track_count, get_track, search_tracks, find_duplicate_tracks, get_track_submissions, get_tag_taxonomy, get_suggested_tags, wait_for_auto_tag |
create:tracks | upload_track_by_url |
update:tracks | update_track_details, update_track_tags, trigger_auto_tag, batch_auto_tag, apply_suggested_tags, upload_artwork, and wait_for_auto_tag with trigger: true |
read:playlists | list_playlists, get_playlist |
create:playlists | create_playlist, add_tracks_to_playlist |
update:playlists | update_playlist, remove_track_from_playlist, reorder_playlist |
read:composers | list_composers, get_composer_count |
read:composer | get_composer |
create:composer | create_composer |
update:composer | update_composer |
delete:composer | delete_composer |
read:analytics | get_dashboard, get_entity_stats, get_top_tracks |
read:briefs | list_briefs, get_brief_submissions |
Suggested key profiles
Read-only assistant. Safe to hand to anyone who should look but not touch:
read:tracks, read:playlists, read:composers, read:composer, read:analytics, read:briefsLibrarian. Can tag, organise and build playlists, but not upload or delete:
read:tracks, update:tracks, read:playlists, create:playlists, update:playlists,
read:composers, read:composer, read:analytics, read:briefsEverything. Every tool works:
read:tracks, create:tracks, update:tracks,
read:playlists, create:playlists, update:playlists,
read:composers, read:composer, create:composer, update:composer, delete:composer,
read:analytics, read:briefsA key created from Settings → Integrations has this full set. Narrow it in Tools → Integration.
Composer scopes
Listing and counting use read:composers; fetching one uses read:composer.
Grant both or the assistant will be able to list composers and then fail to
open any of them.
Credits
search_tracks costs one credit per call from the connected account's
balance, the same as POST /tracks/search. No other tool is
metered.
Revoking access
Revoke or rotate the key in Postal. OAuth tokens minted from it stop working on their next refresh, at most one hour later. The direct-header path stops immediately.