Authorization Code Flow

The Authorization Code flow is designed for applications where users authenticate directly. It provides the highest level of security through a two-step process.

Step 1: Redirect to Authorization

Redirect the user to our authorization endpoint:

GET /oauth/authorize?
    response_type=code
    &client_id=YOUR_CLIENT_ID
    &redirect_uri=https://yourapp.com/callback
    &scope=openid profile:read email
    &state=random_state_value

Parameters

`response_type`	Must be `code`
`client_id`	Your application's client ID
`redirect_uri`	Where to redirect after authorization
`scope`	Space-separated list of scopes
`state`	Random value to prevent CSRF attacks

Step 2: Handle the Callback

After the user authorizes, they'll be redirected to your callback URL with a code:

https://yourapp.com/callback?code=AUTH_CODE&state=random_state_value

Step 3: Exchange Code for Tokens

Exchange the authorization code for an access token:

POST /oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&code=AUTH_CODE
&redirect_uri=https://yourapp.com/callback
&client_id=YOUR_CLIENT_ID
&client_secret=YOUR_CLIENT_SECRET

Response

{
    "access_token": "eyJhbGciOiJIUzI1NiIs...",
    "token_type": "Bearer",
    "expires_in": 3600,
    "refresh_token": "dGhpcyBpcyBhIHJlZnJl...",
    "scope": "openid profile:read email"
}

PKCE Support

For public clients (mobile apps, SPAs), use PKCE for additional security:

# Authorization request includes:
&code_challenge=BASE64URL(SHA256(code_verifier))
&code_challenge_method=S256

# Token request includes:
&code_verifier=YOUR_ORIGINAL_CODE_VERIFIER