Overview

Exchanges an OAuth Authorization Code for an Access Token. This endpoint is the final step in the OAuth 2.0 Authorization Code flow.

This endpoint does not require authentication headers - authentication is performed via the client_id and client_secret in the request body.

Prerequisites

Before using this endpoint, you must:

1. Create an OAuth Application

Create an app using POST /platform/v1/apps with a Directory token. This returns:

• client_id: Your OAuth Client ID
• client_secret: Your OAuth Client Secret (shown only once - store securely!)

Example app creation request:

{
  "name": "My OAuth App",
  "app_code_name": "myoauthapp",
  "redirect_uri": "https://myapp.example.com/oauth/callback",
  "scopes": ["openid"]
}

2. Obtain an Authorization Code

Redirect users to the authorization endpoint to obtain consent:

GET /oauth/authorize?response_type=code&client_id={client_id}&redirect_uri={redirect_uri}&scope={scopes}&state={state}

After user authorization, they are redirected to your redirect_uri with:

• code: The authorization code (use this in the token request)
• state: The state parameter you provided (verify this matches)

3. Exchange Code for Token

Call this endpoint (POST /oauth/token) with the authorization code to receive an access token.

Complete OAuth Flow Diagram

1. App Creation (one-time setup):
   POST /platform/v1/apps → Returns client_id, client_secret

2. User Authorization (browser redirect):
   User → /oauth/authorize → User grants permission → Redirect to app with code

3. Token Exchange (server-to-server):
   POST /oauth/token (with code) → Returns access_token

4. API Access:
   Use access_token in Authorization header for subsequent API calls

Important Notes

• Authorization codes are single-use - once exchanged, they cannot be reused
• Authorization codes expire quickly - exchange them immediately after receiving
• This endpoint cannot be tested in isolation - it requires an authorization code from the user authorization flow
• Store client_secret securely - it is only displayed once during app creation

Available for Staff, Directory, and Client tokens