LiveUpdated 5 May 2026

Authentication & Scopes

Roster supports OAuth 2.0 Bearer tokens and API keys for approved integrations.

OAuth Bearer tokens

Send OAuth access tokens in the Authorization header:

Authorization: Bearer YOUR_ACCESS_TOKEN

Access tokens are short-lived. Refresh tokens are long-lived credentials and must be stored securely by confidential clients.

API keys

Where API keys are issued, send the key in the X-API-Key header:

X-API-Key: YOUR_API_KEY

Do not put API keys or access tokens in query strings.

Confidential clients

Confidential OAuth clients must send YOUR_CLIENT_SECRET when exchanging authorization codes, refreshing tokens, revoking tokens, or introspecting tokens.

Token handling

Store client secrets and refresh tokens only on your server.
Never expose client secrets in browser code or mobile apps.
Treat access tokens as sensitive credentials.
Refresh tokens rotate on successful refresh, so replace the stored refresh token with the newest value.
Expired or revoked tokens must be replaced through the OAuth flow.

Public scopes

Scopes determine what an integration can do. Request only the scopes your application needs.

Scope	Purpose
`imports:write`	Create import sessions and submit royalty rows.
`prepared_runs:read`	Read prepared run status and preview groups.
`prepared_runs:write`	Start or update a prepared run.
`prepared_runs:commit`	Commit a prepared run into statements.
`runs:read`	Read royalty run metadata available to your integration.
`statements:read`	Read statements.
`statement_lines:read`	Read statement line items.
`statement_aggregates:read`	Read statement aggregate summaries.
`statements:write`	Create or update permitted statement-related resources where enabled.

Error response format

{
  "ok": false,
  "error": {
    "code": "invalid_scope",
    "message": "The requested scope is not available for this client."
  }
}

Common authentication errors include invalid_client, invalid_token, invalid_scope, and insufficient_scope.

Last updated 3 May 2026View changelog

Overview API Endpoints