OAuth 2.1 Token Endpoint

Token Endpoint requirements specific to OAuth 2.1 (beyond OpenID Connect).

Endpoint Requirements

HTTP Method

• MUST use POST method
• Other methods not allowed

Content Type

• MUST accept application/x-www-form-urlencoded
• UTF-8 character encoding

TLS

• MUST use HTTPS
• Except localhost for development

CORS Support

For browser-based apps:

• Token endpoint MUST support CORS headers
• Return appropriate Access-Control-Allow-Origin

HTTP/1.1 200 OK
Access-Control-Allow-Origin: https://client.example.com
Content-Type: application/json

Supported Grant Types

authorization_code

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

grant_type=authorization_code
&code=SplxlOBeZQQYbYS6WxSbIA
&code_verifier=dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk

refresh_token

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

grant_type=refresh_token
&refresh_token=tGzv3JOkF0XG5Qx2TlKWIA

client_credentials

POST /token HTTP/1.1
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials

Token Request Processing

Client Authentication

def process_token_request(request):
    # 1. Authenticate confidential clients
    if client.is_confidential:
        if not authenticate_client(request):
            return error_response("invalid_client")
    
    # 2. Validate grant type specific parameters
    # 3. Issue tokens

Parameter Handling

• MUST ignore unrecognized parameters
• Parameters without value treated as omitted
• Parameters MUST NOT be included more than once

Token Response

Success Response

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store

{
  "access_token": "2YotnFZFEjr1zCsicMWpAA",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "tGzv3JOkF0XG5Qx2TlKWIA",
  "scope": "openid profile"
}

Required Fields

Field	Description
access_token	REQUIRED. The access token
token_type	REQUIRED. Type of token (e.g., "Bearer")

Optional Fields

Field	Description
expires_in	RECOMMENDED. Lifetime in seconds
refresh_token	OPTIONAL. Refresh token
scope	RECOMMENDED if same as request, REQUIRED if different

Token Type

• Value is case-insensitive
• Bearer, bearer, BEARER are all valid

Required Headers

Cache-Control

Cache-Control: no-store

MUST include in any response containing tokens.

Pragma (Legacy)

Pragma: no-cache

May include for legacy HTTP/1.0 compatibility.

Error Response

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "error": "invalid_grant",
  "error_description": "Authorization code expired",
  "error_uri": "https://example.com/docs/errors#invalid_grant"
}

Error Codes

Error	Description
invalid_request	Missing/invalid parameter
invalid_client	Client authentication failed (401 status)
invalid_grant	Invalid grant (code, refresh_token, etc.)
unauthorized_client	Client not authorized for grant type
unsupported_grant_type	Grant type not supported
invalid_scope	Invalid/unknown scope

Error Field Character Restrictions

• error: %x20-21 / %x23-5B / %x5D-7E
• error_description: %x20-21 / %x23-5B / %x5D-7E
• error_uri: URI-reference syntax

Authorization Code Grant Specifics

Request Parameters

Parameter	Requirement
grant_type	REQUIRED. Value: authorization_code
code	REQUIRED. The authorization code
code_verifier	REQUIRED if code_challenge was present
client_id	REQUIRED if not authenticating otherwise

Validation

1. Authenticate client if confidential
2. Verify code issued to this client
3. Verify code is valid and not expired
4. Verify code_verifier (see PKCE skill)
5. Return access token only once per code

Code Reuse Handling

def handle_code_reuse(code):
    if code.already_used:
        # MUST deny request
        # SHOULD revoke all tokens from this code
        revoke_tokens_for_code(code)
        return error_response("invalid_grant")

Refresh Token Grant Specifics

Request Parameters

Parameter	Requirement
grant_type	REQUIRED. Value: refresh_token
refresh_token	REQUIRED. The refresh token
scope	OPTIONAL. Must not exceed original scope

Public Client Requirements

For public clients, refresh tokens MUST be either:

• Sender-constrained (bound to client proof)
• One-time use (rotation)

Refresh Token Rotation

def handle_refresh_token(refresh_token):
    # Issue new access token
    access_token = generate_access_token()
    
    # Optionally rotate refresh token
    if should_rotate:
        new_refresh_token = generate_refresh_token()
        invalidate(refresh_token)
        return {
            "access_token": access_token,
            "refresh_token": new_refresh_token
        }
    
    return {"access_token": access_token}

Client Credentials Grant Specifics

Request Parameters

Parameter	Requirement
grant_type	REQUIRED. Value: client_credentials
scope	OPTIONAL

Requirements

• MUST only be used by confidential clients
• MUST authenticate client

Removed from OAuth 2.1

These grant types are NOT in OAuth 2.1:

• Implicit Grant (response_type=token)
• Resource Owner Password Credentials Grant

Implementation Checklist

1. Use POST method only
2. Accept application/x-www-form-urlencoded
3. Use HTTPS (except localhost)
4. Support CORS for browser apps
5. Include Cache-Control: no-store
6. Support authorization_code grant
7. Support refresh_token grant
8. Support client_credentials grant
9. Validate PKCE code_verifier
10. Enforce single-use authorization codes
11. Revoke tokens on code reuse
12. Handle refresh token rotation for public clients
13. Return proper error responses
14. Ignore unrecognized parameters