OAuth2 Integration

If you are building a third-party application that accesses MTG Rack data on behalf of other users, you need to implement OAuth2. MTG Rack supports the Authorization Code flow with PKCE for public clients and the Client Credentials flow for server-to-server communication.

Registering Your Application

Before you can use OAuth2, register your application in the Developer Portal. You will receive a Client ID and, for confidential clients, a Client Secret. You also need to register one or more redirect URIs — these are the URLs your app will handle the authorization callback on.

Confidential vs Public Clients

Confidential clients (server-side apps) can securely store a client secret and use the standard Authorization Code flow. Public clients (SPAs, mobile apps, CLIs) cannot keep a secret safe and must use PKCE. MTG Rack requires PKCE for all public clients.

Authorization Code Flow (with PKCE)

This is the recommended flow for most applications. It works for both confidential and public clients.

Step 1 — Redirect the user to authorize:

GET https://mtgrack.com/oauth/authorize
  ?response_type=code
  &client_id=your_client_id
  &redirect_uri=https://yourapp.com/callback
  &scope=collection:read decks:read
  &state=random_csrf_token
  &code_challenge=BASE64URL_SHA256_OF_VERIFIER
  &code_challenge_method=S256

Step 2 — Exchange the authorization code for tokens:

POST https://mtgrack.com/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&code=AUTH_CODE_FROM_CALLBACK
&redirect_uri=https://yourapp.com/callback
&client_id=your_client_id
&code_verifier=ORIGINAL_PKCE_VERIFIER

Response:

{
  "access_token": "mtr_at_...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "mtr_rt_...",
  "scope": "collection:read decks:read"
}

Client Credentials Flow

Use this flow for server-to-server integrations where no user interaction is involved. This flow does not issue a refresh token since the client can request a new access token at any time using its credentials.

POST https://mtgrack.com/oauth/token
Content-Type: application/x-www-form-urlencoded
Authorization: Basic BASE64(client_id:client_secret)

grant_type=client_credentials
&scope=cards:read

Limited Scopes

The Client Credentials flow only supports scopes that do not require a user context, such as cards:read. User-specific scopes like collection:read require the Authorization Code flow.

Refreshing Tokens

Access tokens expire after 1 hour. Use the refresh token to obtain a new access token without prompting the user again:

POST https://mtgrack.com/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token
&refresh_token=mtr_rt_...
&client_id=your_client_id

Refresh tokens are single-use — each refresh response includes a new refresh token. The old one is immediately invalidated. Refresh tokens expire after 30 days of inactivity.

Registering Your Application

Confidential vs Public Clients

Authorization Code Flow (with PKCE)

This is the recommended flow for most applications. It works for both confidential and public clients.

Step 1 — Redirect the user to authorize:

GET https://mtgrack.com/oauth/authorize ?response_type=code &client_id=your_client_id &redirect_uri=https://yourapp.com/callback &scope=collection:read decks:read &state=random_csrf_token &code_challenge=BASE64URL_SHA256_OF_VERIFIER &code_challenge_method=S256

Step 2 — Exchange the authorization code for tokens:

POST https://mtgrack.com/oauth/token Content-Type: application/x-www-form-urlencoded grant_type=authorization_code &code=AUTH_CODE_FROM_CALLBACK &redirect_uri=https://yourapp.com/callback &client_id=your_client_id &code_verifier=ORIGINAL_PKCE_VERIFIER

Response:

{ "access_token": "mtr_at_...", "token_type": "Bearer", "expires_in": 3600, "refresh_token": "mtr_rt_...", "scope": "collection:read decks:read" }

Client Credentials Flow

POST https://mtgrack.com/oauth/token Content-Type: application/x-www-form-urlencoded Authorization: Basic BASE64(client_id:client_secret) grant_type=client_credentials &scope=cards:read

Limited Scopes

The Client Credentials flow only supports scopes that do not require a user context, such as cards:read. User-specific scopes like collection:read require the Authorization Code flow.

Refreshing Tokens

Access tokens expire after 1 hour. Use the refresh token to obtain a new access token without prompting the user again:

POST https://mtgrack.com/oauth/token Content-Type: application/x-www-form-urlencoded grant_type=refresh_token &refresh_token=mtr_rt_... &client_id=your_client_id

Refresh tokens are single-use — each refresh response includes a new refresh token. The old one is immediately invalidated. Refresh tokens expire after 30 days of inactivity.