Scopes

Every scope an API key or OAuth grant can carry, and what each one unlocks.

1 min read

Each /v1 endpoint requires exactly one scope, shown on its card in the API reference. A credential without it gets 403 scope_missing, and the error’s required_scope names what was missing.

Scope	Consent screen	Grants
`workspace:read`	Full read access	Every `*:read` scope. The key preset “Read”.
`workspace:write`	Full write accesswrite	Every `:read` and `:write` scope. The key preset “Read & write”.
`shows:read`	Shows	Workspace, shows, subnetworks, team, plan, integrations, public URLs.
`shows:write`	Edit showswrite	Show and network profile edits, default EMV.
`analytics:read`	Analytics	Analytics, content, categories, hosts, account dedup.
`episodes:read`	Episodes	Episodes, search, transcripts.
`episodes:write`	Edit episodeswrite	Tags, goals, Substack downloads.
`clusters:read`	Clusters	Clusters, cluster reports and timelines, cluster builder reads.
`clusters:write`	Edit clusterswrite	Create, update, merge, delete, nodes, builds, suggestions, sources.
`campaigns:read`	Campaigns	Campaigns, brands, air checks, CPM insights.
`campaigns:write`	Edit campaignswrite	Campaigns, slots, brands, cluster links.
`reports:read`	Reports	Shared reports, templates, automations.
`reports:write`	Edit reportswrite	Create and delete reports and templates, disable automations.
`sponsors:read`	Sponsors	Sponsor matching, network opportunities, sponsorship packages.
`library:read`	Library & research	Library files, web research, podcast search, insertion-order parsing.
`refresh:write`	Refresh datawrite	Platform refresh, cluster refresh, Spotify and Apple data requests (metered).
`webhooks:read`	Webhooks	Webhook endpoints, deliveries, events.
`webhooks:write`	Manage webhookswrite	Create, update, test, roll secrets, delete endpoints.
`offline_access`	Stay connected	A refresh token on the OAuth token response.

How scopes combine#

Umbrella scopes. workspace:read includes every *:read scope. workspace:write includes every *:read and *:write scope. These are the Read and Read & write key presets.
Write implies read. campaigns:write also grants campaigns:read, and so on for each resource.
offline_access only matters for OAuth: it makes the token response include a refresh token. API keys ignore it.

Choosing scopes#

Job	Scopes
Nightly reach export	`analytics:read` `shows:read`
Campaign delivery dashboard	`campaigns:read` `analytics:read`
Create campaigns from insertion orders	`campaigns:write` `library:read`
Episode cluster automation	`clusters:write` `episodes:read`
Webhook management	`webhooks:write`
Trigger data refreshes	`refresh:write` (metered, needs `confirm`)

MCP sessions#

AI assistants connected through MCP with an OAuth token need workspace:read, plus workspace:write to use write tools. The consent screen shows those as “Full read access” and “Full write access”.