OAuth 2.0 Guide

Roster supports the OAuth 2.0 authorization code flow for approved partner applications.

Flow overview

1. Redirect the user to the authorization URL with your client ID, redirect URI, and requested scopes.
2. The user reviews and approves the requested access.
3. Roster redirects back to your redirect URI with an authorization code.
4. Your server exchanges the code for tokens.
5. Use the access token to call the API.
6. Use the refresh token to obtain new access tokens when needed.

Authorization request

https://api.rosterroyalties.com/oauth/authorize?response_type=code&client_id=YOUR_CLIENT_ID&redirect_uri=https%3A%2F%2Fexample.com%2Fcallback&scope=statements%3Aread%20imports%3Awrite&state=random_state_value

Recommended parameters:

Token exchange

Exchange the authorization code from your backend server.

curl -X POST "https://api.rosterroyalties.com/oauth/token" \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "authorization_code",
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET",
    "code": "AUTHORIZATION_CODE",
    "redirect_uri": "https://example.com/callback"
  }'

Example response:

{
  "access_token": "YOUR_ACCESS_TOKEN",
  "refresh_token": "YOUR_REFRESH_TOKEN",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "statements:read imports:write"
}

Refreshing tokens

curl -X POST "https://api.rosterroyalties.com/oauth/token" \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "refresh_token",
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET",
    "refresh_token": "YOUR_REFRESH_TOKEN"
  }'

Refresh tokens rotate on successful refresh. Store the new refresh token returned by the response.

Revocation

curl -X POST "https://api.rosterroyalties.com/oauth/revoke" \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET",
    "token": "YOUR_ACCESS_TOKEN"
  }'

Token introspection

Confidential clients can validate token state from their backend.

curl -X POST "https://api.rosterroyalties.com/oauth/introspect" \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET",
    "token": "YOUR_ACCESS_TOKEN"
  }'

OAuth errors

{
  "ok": false,
  "error": {
    "code": "invalid_client",
    "message": "Client authentication failed."
  }
}

Common OAuth error codes include invalid_client, invalid_grant, invalid_scope, invalid_token, and access_denied.