Exchanges an OAuth Code for an Access Token

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