Getting started
Authentication
Keys, the scopes that limit them, and OAuth tokens.
On this page
Every call carries a key, or an OAuth access token, in the Authorization header:
Authorization: Bearer sm_live_…Keys#
Owners and admins make keys in Workspace › API. A key:
- acts for the member who holds it, and is pinned to one organization;
- may do what its scopes allow and what that member may do in the workspace, both checked on every call;
- is shown once; only its SHA-256 is stored;
- can be limited to IP addresses or ranges, given an end date, rolled with a grace period, taken over by another owner or admin, and revoked.
Changing what a key may do (its scopes, addresses or sub-labels) takes an authenticator code.
| Prefix | What it is |
|---|---|
sm_live_… | A live key, on your real catalogue |
sm_test_… | A sandbox key, in a copy of your organization where nothing is real |
sm_oat_… | An OAuth access token, an hour long |
sm_ort_… | An OAuth refresh token, 60 days, used once |
Scopes#
Give each key only the scopes its system needs. Write scopes include the read scope of the same thing.
| Scope | What it allows |
|---|---|
releases:read | Releases, their tracks, review and delivery status, codes and store links. |
releases:write | Drafts, tracks, splits, artwork and audio files. |
releases:submit | Submit releases for review and ask for takedowns. |
artists:read | The organization's artist roster. |
artists:write | Add artists to the roster and change their details. |
labels:read | The organization's labels and imprints. |
labels:write | Add labels and imprints and change their details. |
finance:read | Balance, ledger, earnings, published royalty statements and payouts. |
payouts:write | Ask for payouts to the organization's saved payout methods, once an owner or admin allows it in the API tab. |
webhooks:manage | Register, change and test webhook endpoints. |
Payout requests also need an owner or admin to allow them under Workspace › API › Settings, and go only to payout methods saved in the workspace.
OAuth tokens#
Software other labels connect uses OAuth apps instead of keys: the label approves the app on a consent screen, and the app gets tokens that act for that member within the scopes they allowed. Tokens are sent the same way as keys.