Oauth21 Token Endpoint

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

Optional Fields

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 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

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

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

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

Source: maronnjapan/maronn-openid-provider — distributed by TomeVault.