Authorization Code Flow
------------------------
This is the standard OAuth 2.0 flow for web applications. It is described in full in Getting Started. Key points:
- Tokens expire after 2 hours (access_token) and 30 days (refresh_token)
- Always request the minimum scopes your app actually needs
- Store the refresh token securely — it can be used to obtain new access tokens
Refreshing Access Tokens
-------------------------
When an access token expires, use the refresh token to get a new one without requiring the user to re-authorize:
POST /oauth/token
Content-Type: application/x-www-form-urlencoded
grant_type=refresh_token
&refresh_token=YOUR_REFRESH_TOKEN
&client_id=YOUR_CLIENT_ID
&client_secret=YOUR_CLIENT_SECRET
Response is identical to the authorization code exchange — you receive a new access_token and refresh_token.
Token Endpoint
--------------
POST /oauth/token
All requests must be:
- Content-Type: application/x-www-form-urlencoded (not JSON)
- Confidential clients: include client_id and client_secret in the body
Supported grant_types:
- authorization_code — initial token exchange
- refresh_token — renew tokens
- client_credentials — machine-to-machine (no user context; requires special approval)
Token Revocation
----------------
To invalidate a token immediately (e.g., on user sign-out from your app):
POST /oauth/revoke
Content-Type: application/x-www-form-urlencoded
token=ACCESS_OR_REFRESH_TOKEN
&client_id=YOUR_CLIENT_ID
&client_secret=YOUR_CLIENT_SECRET
PKCE for Public Clients
-----------------------
If your app cannot keep a client secret (mobile app, single-page app), register it as a Public client and use PKCE:
1. Generate a code_verifier: a random 43-128 character string
2. Derive code_challenge: BASE64URL(SHA256(code_verifier))
3. Add to the authorization URL:
&code_challenge=HASH&code_challenge_method=S256
4. Include code_verifier (not code_challenge) in the token exchange
Public clients do not send client_secret. Security is provided by the code verifier, which proves the token request came from the same party that initiated the authorization.