Velveteen API Scopes
Updated June 13, 2026
Scopes control what an API key can do. There are six: catalog read and write, pitches read and write, and royalties read and write. You choose a key's scopes when you create it, and a request fails if the key lacks the scope it needs.
Scopes keep keys least-privilege. Give a key only the scopes the integration needs.
The six scopes
catalog:read
Read releases, tracks, artists, labels, people, and publishing houses.
catalog:write
Create, update, and delete catalog entities.
pitches:read
Read pitches.
pitches:write
Create, update, and withdraw pitches.
royalties:read
Read balances, earnings, and payout history.
royalties:write
Request payouts.
Choosing scopes
Pick the smallest set that covers what your integration does. A read-only tool needs only the read scopes.
If a key calls an endpoint it is not scoped for, the request is rejected. Create a new key rather than over-scoping by default.
Tip
Frequently asked questions
Can I change a key's scopes later?+
Scopes are chosen at creation. To change them, create a new key with the scopes you need and revoke the old one.
What happens without the right scope?+
The request is rejected with a forbidden error. The key needs the matching scope.
Which scope do I need to read my catalog?+
catalog:read covers releases, tracks, artists, labels, people, and publishing houses.
How do I request a payout via the API?+
Use a key with royalties:write. royalties:read alone cannot request payouts.
Related articles
API keys
Create a key with a name and scopes, copy it once at creation, revoke it anytime, and the limit of ten active keys per account.
Endpoints
The resource groups the API covers, how pagination works, and the standard error codes the API returns.
Overview
Build on Velveteen: API keys, Bearer authentication, scopes, and the catalog, pitching, and royalty endpoints. Available on the Pro and Label plans.