OAuth 2.0 PKCE flow, token exchange, session management, DCR, resource indicators

Overview

Fast.io implements OAuth 2.0 with PKCE (Proof Key for Code Exchange) for secure authorization without passing user credentials through the client application. This is the recommended auth method for desktop apps, mobile apps, and MCP-connected agents.

Key characteristics:

• S256 challenge method only (plain not supported)
• Access tokens last 1 hour (3600 seconds)
• Refresh tokens last 30 days
• Authorization codes last 5 minutes
• Authorization requests last 10 minutes
• Supports SSO (user signs in via browser, supports federated login)
• No user password passes through the agent/client
• Dynamic Client Registration (RFC 7591/7592) for automated client onboarding
• Client ID Metadata Document (CIMD) for URL-based client identification
• Resource Indicators (RFC 8707) for audience-restricted JWT access tokens
• Scoped access tokens (JWT v2.0) with entity-level restrictions and agent identity
• Metadata discovery (RFC 8414, RFC 9728) for automated server/resource configuration

Endpoint Summary

Metadata Discovery

GET /.well-known/oauth-authorization-server/

RFC 8414 Authorization Server Metadata. Returns server configuration for automated client setup.

curl -X GET "https://api.fast.io/.well-known/oauth-authorization-server/"

Response (200 OK):

{
  "issuer": "https://api.fast.io",
  "authorization_endpoint": "https://api.fast.io/current/oauth/authorize/",
  "token_endpoint": "https://api.fast.io/current/oauth/token/",
  "revocation_endpoint": "https://api.fast.io/current/oauth/revoke/",
  "registration_endpoint": "https://api.fast.io/current/oauth/register/",
  "response_types_supported": ["code"],
  "grant_types_supported": ["authorization_code", "refresh_token"],
  "token_endpoint_auth_methods_supported": ["none"],
  "code_challenge_methods_supported": ["S256"],
  "resource_indicators_supported": true,
  "service_documentation": "https://fast.io/docs"
}

Response Fields:

Error Responses:

GET /.well-known/oauth-protected-resource/

RFC 9728 Protected Resource Metadata. Returns resource server configuration.

curl -X GET "https://api.fast.io/.well-known/oauth-protected-resource/"

Response (200 OK):

{
  "resource": "https://mcp.fast.io/mcp",
  "authorization_servers": ["https://api.fast.io"],
  "bearer_methods_supported": ["header"],
  "scopes_supported": ["user"]
}

Response Fields:

Error Responses:

Dynamic Client Registration

POST /current/oauth/register/

RFC 7591 Dynamic Client Registration. Register a new OAuth client programmatically.

Request Parameters:

curl -X POST "https://api.fast.io/current/oauth/register/" \
  -H "Content-Type: application/json" \
  -d '{
    "client_name": "My MCP Client",
    "redirect_uris": ["http://localhost:3000/callback", "http://127.0.0.1:3000/callback"]
  }'

Response (200 OK):

{
  "result": true,
  "response": {
    "client_id": "dyn_a1b2c3d4e5f6g7h8i9j0",
    "client_name": "My MCP Client",
    "redirect_uris": [
      "http://localhost:3000/callback",
      "http://127.0.0.1:3000/callback"
    ],
    "token_endpoint_auth_method": "none",
    "grant_types": ["authorization_code", "refresh_token"],
    "response_types": ["code"],
    "registration_access_token": "rat_a1b2c3d4e5f6g7h8...",
    "registration_client_uri": "https://api.fast.io/current/oauth/register/"
  }
}

Response Fields:

Error Responses (RFC 7591 format — bare JSON, no platform envelope):

PUT /current/oauth/register/

RFC 7592 Dynamic Client Registration Management. Update an existing client registration. Requires the registration_access_token from the POST registration response. Only clients whose redirect URIs all point to localhost, 127.0.0.1, [::1], or ::1 may self-update.

Request Parameters:

At least one of client_name or redirect_uris must be provided.

curl -X PUT "https://api.fast.io/current/oauth/register/" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer rat_a1b2c3d4e5f6g7h8..." \
  -d '{
    "client_id": "dyn_a1b2c3d4e5f6g7h8i9j0",
    "client_name": "My Updated MCP Client",
    "redirect_uris": ["http://localhost:8080/callback"]
  }'

Response (200 OK):

{
  "result": true,
  "response": {
    "client_id": "dyn_a1b2c3d4e5f6g7h8i9j0",
    "client_name": "My Updated MCP Client",
    "redirect_uris": ["http://localhost:8080/callback"],
    "token_endpoint_auth_method": "none",
    "grant_types": ["authorization_code", "refresh_token"],
    "response_types": ["code"]
  }
}

Response Fields:

Error Responses (RFC 7591 format — bare JSON):

The grant_types, response_types, and token_endpoint_auth_method fields cannot be changed via self-update. If redirect_uris is provided, it fully replaces the existing set. If only client_name is provided, existing redirect URIs are preserved.

Client ID Metadata Document (CIMD)

CIMD allows OAuth clients to use an HTTPS URL as their client_id instead of pre-registering or using Dynamic Client Registration. The authorization server fetches metadata from the URL to get client information on-the-fly. This is the MCP specification's preferred client registration method.

How It Works

1. Detection: If the client_id parameter starts with https://, the server treats it as a CIMD URL.
2. Fetch: The server fetches the JSON metadata document from the CIMD URL.
3. Validation: The document must contain:
   • client_id matching the fetched URL exactly
   • redirect_uris array containing the requested redirect URI
   • grant_types including authorization_code
   • response_types including code
   • token_endpoint_auth_method set to none
4. Caching: Validated documents are cached for 1 hour to avoid repeated fetches.
5. Flow: The CIMD URL is used as the client_id throughout the authorization flow (authorize, token exchange, refresh).

CIMD Document Format

The metadata document is a JSON file served at an HTTPS URL with Content-Type: application/json:

{
  "client_id": "https://example.com/oauth/client-metadata",
  "client_name": "Example App",
  "redirect_uris": ["http://localhost:8080/callback"],
  "grant_types": ["authorization_code"],
  "response_types": ["code"],
  "token_endpoint_auth_method": "none"
}

Optional fields: client_uri (URL to the client's home page), logo_uri (URL to the client's logo image).

Security Constraints

Using CIMD in the Authorization Flow

Use the CIMD URL directly as the client_id parameter:

GET /current/oauth/authorize/?client_id=https://example.com/oauth/client-metadata&redirect_uri=http://localhost:8080/callback&code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM&code_challenge_method=S256&state=xyz123

The token endpoint also uses the CIMD URL as client_id — it matches by string comparison against the value stored during authorization.

Error Scenarios

Complete PKCE Flow

Step 0: Discover Server Configuration (Optional)

Fetch server metadata for automated setup:

1. CLIENT -> API: Discover authorization server
   GET /.well-known/oauth-authorization-server/
   -> Returns endpoints, supported grant types, PKCE methods

2. CLIENT -> API: Discover protected resource (if needed)
   GET /.well-known/oauth-protected-resource/
   -> Returns resource URL and authorization servers

Step 0b: Register Client (If Needed)

If the client does not have a registered client_id, there are two options:

Option A: Use a CIMD URL as client_id — If the client publishes a metadata document at an HTTPS URL, use that URL directly as the client_id. No registration step needed.

Option B: Use Dynamic Client Registration:

CLIENT -> API: Register client
POST /current/oauth/register/
Content-Type: application/json

{"client_name": "My Agent", "redirect_uris": ["http://localhost:8080/callback"]}

-> Returns client_id, redirect_uris, registration_access_token, etc.

Step 1: Generate PKCE Parameters (Client-Side)

Before initiating the flow, generate the PKCE code verifier and challenge:

code_verifier = random_string(43-128 characters, URL-safe: [A-Za-z0-9-._~])
code_challenge = base64url_encode(sha256(code_verifier))
code_challenge_method = "S256"

The code_challenge will always be exactly 43 characters.

Step 2: Initiate Authorization

GET /current/oauth/authorize/

Initiates the authorization flow. By default, issues a 302 Found redirect to the login/consent page. This is the browser-facing entry point that MCP clients open in the user's browser.

JSON mode: Add response_format=json to receive a JSON response instead of a redirect (for programmatic callers).

Query Parameters:

Scope type values (scope parameter):

# Standard browser flow (302 redirect)
curl -v "https://api.fast.io/current/oauth/authorize/?client_id=my-app&redirect_uri=http%3A%2F%2Flocalhost%3A8080%2Fcallback&response_type=code&code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM&code_challenge_method=S256&state=abc123xyz"

# JSON mode (programmatic)
curl "https://api.fast.io/current/oauth/authorize/?client_id=my-app&redirect_uri=http%3A%2F%2Flocalhost%3A8080%2Fcallback&response_type=code&code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM&code_challenge_method=S256&state=abc123xyz&response_format=json"

Response (default — 302 Found):

Location: https://go.fast.io/connect?auth_request_id=a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2

Response (response_format=json — 200 OK):

{
  "result": true,
  "response": {
    "auth_request_id": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2",
    "client_name": "My App",
    "scope": "user"
  }
}

Response Fields (JSON mode):

Error Responses (standard platform envelope):

POST /current/oauth/authorize/

Complete authorization after user login. Issues the authorization code. Called by the web application (not the client directly) with the user's active session.

Request Parameters:

curl -X POST "https://api.fast.io/current/oauth/authorize/" \
  -H "Authorization: Bearer {jwt_token}" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "auth_request_id=a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2"

Response (200 OK):

{
  "result": true,
  "response": {
    "redirect_uri": "http://localhost:8080/callback?code=abc123def456abc123def456abc123def456abc123def456abc123def456abc123de&state=abc123xyz",
    "redirect_mode": "redirect"
  }
}

Response Fields:

Error Responses:

GET /current/oauth/authorize/info/

Validate an authorization request and return client information (app name, requested scope). Used by the web frontend to display a consent screen before the user confirms.

Query Parameters:

curl "https://api.fast.io/current/oauth/authorize/info/?auth_request_id=a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2"

Response (valid request — 200 OK):

{
  "result": true,
  "response": {
    "valid": true,
    "client_name": "My App",
    "scope": "user",
    "agent_name": "My MCP Agent",
    "redirect_mode": "redirect",
    "redirect_uri": "http://localhost:8080/callback"
  }
}

Response (invalid or expired — 200 OK):

{
  "result": true,
  "response": {
    "valid": false
  }
}

Response Fields:

This endpoint never returns an error for invalid auth_request_id. It returns valid: false instead, preventing information leakage about authorization request existence.

Step 3: User Approves in Browser

The user opens the authorization URL, signs in (supports SSO), and approves access. The browser either:

• Redirects to redirect_uri with ?code={authorization_code}&state={state}
• Displays the authorization code for the user to copy back to the agent (when redirect_mode is "button")

Step 4: Exchange Code for Tokens

POST /current/oauth/token/

Exchange an authorization code for access and refresh tokens, or refresh an existing access token.

Important: This endpoint returns bare JSON responses (RFC 6749 format, no platform envelope) for compatibility with standard OAuth clients, including MCP hosts.

Authorization Code Exchange

Request Parameters:

curl -X POST "https://api.fast.io/current/oauth/token/" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code&code=abc123def456abc123def456abc123def456abc123def456abc123def456abc123de&code_verifier=dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk&client_id=my-app&redirect_uri=http://localhost:8080/callback"

Response (200 OK — bare JSON, no envelope):

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "dGhpcyBpcyBhIHJlZnJlc2ggdG9rZW4...",
  "scope": "org",
  "scopes": "[\"org:12345:rw\",\"org:67890:rw\"]",
  "agent_name": "My MCP Agent"
}

Response Fields:

Refresh Token Exchange

curl -X POST "https://api.fast.io/current/oauth/token/" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=refresh_token&refresh_token=dGhpcyBpcyBhIHJlZnJlc2ggdG9rZW4...&client_id=my-app"

Response (200 OK — bare JSON): Same format as authorization code exchange. Returns a new access_token and a new refresh_token. The old refresh token is immediately revoked (mandatory token rotation).

Error Responses (RFC 6749 SS5.2 format — bare JSON):

{
  "error": "invalid_grant",
  "error_description": "The authorization code is invalid or has expired."
}

Resource Indicator Enforcement: The resource value is stored in the authorization code during the authorize step. At token exchange, the value is strictly compared. If they do not match — including if one is null and the other is not — the exchange fails. This prevents downgrade attacks where a client omits the resource to obtain an unrestricted token.

Step 5: Use the Access Token

Include the access token in all API requests:

Authorization: Bearer {access_token}

When the access token expires (after 1 hour), use the refresh token to get a new one without requiring user interaction. Refresh proactively before expiration (5-minute buffer recommended) to avoid interruptions.

Token Revocation

POST /current/oauth/revoke/

Revoke a refresh token (logout). Implements RFC 7009 (OAuth 2.0 Token Revocation). Always returns success to prevent token enumeration attacks.

Request Parameters:

curl -X POST "https://api.fast.io/current/oauth/revoke/" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "token=dGhpcyBpcyBhIHJlZnJlc2ggdG9rZW4..."

Response (200 OK):

{
  "result": true,
  "response": {
    "result": true
  }
}

Error Responses (RFC 6749 format — bare JSON):

Per RFC 7009, this endpoint always returns success regardless of whether the token was found, was already revoked, or never existed. Always call this endpoint on user logout and clear local token storage regardless of the response.

Session Management

OAuth sessions represent active token grants. Each authorization code exchange creates a session. Sessions have a stable session_id (32-character hex string) that persists across token rotations.

GET /current/oauth/sessions/

List all active (non-expired, non-revoked) OAuth sessions for the authenticated user.

curl -X GET "https://api.fast.io/current/oauth/sessions/" \
  -H "Authorization: Bearer {jwt_token}"

Response (200 OK):

{
  "result": true,
  "response": {
    "sessions": [
      {
        "session_id": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
        "client_id": "my-app",
        "device_name": "Chrome on macOS",
        "device_type": "desktop",
        "ip_address": "192.168.1.100",
        "last_used": "2026-01-22 14:00:00",
        "created": "2026-01-21 14:00:00",
        "expires": "2026-02-21 14:00:00"
      }
    ],
    "count": 1
  }
}

Response Fields:

Error Responses:

GET /current/oauth/sessions/{session_id}/

Get details of a specific OAuth session. The session must belong to the authenticated user.

Path Parameters:

curl -X GET "https://api.fast.io/current/oauth/sessions/a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4/" \
  -H "Authorization: Bearer {jwt_token}"

Response (200 OK):

{
  "result": true,
  "response": {
    "session": {
      "session_id": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
      "client_id": "my-app",
      "device_name": "Chrome on macOS",
      "device_type": "desktop",
      "ip_address": "192.168.1.100",
      "last_used": "2026-01-22 14:00:00",
      "created": "2026-01-21 14:00:00",
      "expires": "2026-02-21 14:00:00"
    }
  }
}

Error Responses:

PATCH /current/oauth/sessions/{session_id}/

Update the device_name and/or agent_name of a specific OAuth session. The session must belong to the authenticated user and must not be revoked.

Path Parameters:

Body Parameters:

At least one of device_name or agent_name must be provided.

curl -X PATCH "https://api.fast.io/current/oauth/sessions/a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4/" \
  -H "Authorization: Bearer {jwt_token}" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "device_name=My%20Work%20Laptop"

Response (200 OK):

{
  "result": true,
  "response": {
    "session": {
      "session_id": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
      "client_id": "my-app",
      "device_name": "My Work Laptop",
      "device_type": "desktop",
      "ip_address": "192.168.1.100",
      "last_used": "2026-01-22 14:00:00",
      "created": "2026-01-21 14:00:00",
      "expires": "2026-02-21 14:00:00"
    }
  }
}

Error Responses:

DELETE /current/oauth/sessions/{session_id}/

Revoke a specific OAuth session. The session must belong to the authenticated user. This operation is idempotent — if the session is already revoked, success is still returned.

Path Parameters:

curl -X DELETE "https://api.fast.io/current/oauth/sessions/a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4/" \
  -H "Authorization: Bearer {jwt_token}"

Response (200 OK):

{
  "result": true,
  "response": {
    "result": true,
    "message": "Session has been revoked."
  }
}

Error Responses:

DELETE /current/oauth/sessions/

Revoke all OAuth sessions (logout everywhere). Optionally exclude the current session for "log out everywhere else" functionality.

Query Parameters:

# Revoke ALL sessions
curl -X DELETE "https://api.fast.io/current/oauth/sessions/" \
  -H "Authorization: Bearer {jwt_token}"

# Revoke all EXCEPT current session
curl -X DELETE "https://api.fast.io/current/oauth/sessions/?exclude_current=true&current_session_id=a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4" \
  -H "Authorization: Bearer {jwt_token}"

Response (200 OK):

{
  "result": true,
  "response": {
    "result": true,
    "message": "All sessions have been revoked."
  }
}

Or when exclude_current is used:

{
  "result": true,
  "response": {
    "result": true,
    "message": "All other sessions have been revoked."
  }
}

Error Responses:

When exclude_current is "true" but current_session_id is not provided, all sessions are revoked.

Token Scope Introspection

GET /current/auth/scopes/

Returns the current token's scope information, auth type, and agent status. Enables clients to discover their token's capabilities without decoding the JWT.

curl -X GET "https://api.fast.io/current/auth/scopes/" \
  -H "Authorization: Bearer {jwt_token}"

Response (200 OK):

{
  "result": true,
  "response": {
    "auth_type": "jwt_v2",
    "scopes": ["org:12345:rw", "org:67890:rw"],
    "scopes_detail": [
      {
        "entity_type": "org",
        "entity_id": "12345",
        "access_mode": "rw",
        "name": "Acme Corp",
        "domain": "acme"
      },
      {
        "entity_type": "org",
        "entity_id": "67890",
        "access_mode": "rw",
        "name": "Beta Inc",
        "domain": "beta"
      }
    ],
    "is_agent": true,
    "agent_name": "My MCP Agent",
    "full_access": false
  }
}

Response Fields:

Scope Detail Fields:

Each entry in scopes_detail contains entity-specific fields:

Error Responses:

Complete PKCE Example Flow

Here is a complete example of the PKCE authorization flow:

0. CLIENT -> API: Discover server configuration (optional)
   GET /.well-known/oauth-authorization-server/
   -> Returns endpoints, grant types, PKCE methods, resource_indicators_supported

0b. CLIENT -> API: Register client dynamically (if no client_id)
   POST /current/oauth/register/
   Content-Type: application/json
   {"client_name": "My Agent", "redirect_uris": ["http://localhost:8080/callback"]}
   -> Returns client_id, registration_access_token

   OR use a CIMD URL as client_id (no registration needed)

1. CLIENT: Generate PKCE parameters
   code_verifier  = "dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk"
   code_challenge = base64url(sha256(code_verifier))
                  = "E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM"

2. CLIENT -> BROWSER: Open authorization URL in user's browser
   GET /current/oauth/authorize/
   ?client_id=my-app
   &redirect_uri=http://localhost:8080/callback
   &response_type=code
   &code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM
   &code_challenge_method=S256
   &state=xyz123
   &resource=https://mcp.fast.io/mcp

3. API -> BROWSER: 302 redirect to login/consent page
   -> Browser lands on login page, user signs in, approves access

4. BROWSER -> CLIENT: Authorization code returned
   http://localhost:8080/callback?code=AUTH_CODE_HERE&state=xyz123
   (or displayed on screen for user to copy)

5. CLIENT -> API: Exchange code for tokens
   POST /current/oauth/token/
   Content-Type: application/x-www-form-urlencoded

   grant_type=authorization_code
   &code=AUTH_CODE_HERE
   &code_verifier=dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk
   &client_id=my-app
   &redirect_uri=http://localhost:8080/callback
   &resource=https://mcp.fast.io/mcp

6. API -> CLIENT: Tokens returned (bare JSON)
   {
     "access_token": "eyJ...",
     "token_type": "Bearer",
     "expires_in": 3600,
     "refresh_token": "eyJ...",
     "scope": "user"
   }

7. CLIENT -> API: Use access token for requests
   GET /current/user/me/details/
   Authorization: Bearer eyJ...

8. CLIENT -> API: Refresh when access token expires
   POST /current/oauth/token/
   Content-Type: application/x-www-form-urlencoded

   grant_type=refresh_token
   &refresh_token=eyJ...
   &client_id=my-app

   -> Returns new access_token + new refresh_token (old one revoked)

9. CLIENT -> API: Revoke on logout
   POST /current/oauth/revoke/
   Content-Type: application/x-www-form-urlencoded

   token=eyJ...

Error Handling

Token and Revoke Endpoints (RFC 6749 SS5.2)

The token (POST /current/oauth/token/) and revoke (POST /current/oauth/revoke/) endpoints return RFC 6749 compliant error responses — bare JSON, not the standard platform envelope:

{
  "error": "invalid_grant",
  "error_description": "The authorization code is invalid or has expired."
}

Registration Endpoint (RFC 7591)

The registration endpoint (POST /current/oauth/register/ and PUT /current/oauth/register/) also returns bare JSON error responses with RFC 7591 error codes:

{
  "error": "invalid_client_metadata",
  "error_description": "The client_name must be between 1 and 128 characters."
}

Other OAuth Endpoints

All other OAuth endpoints (authorize, authorize/info, sessions) use the standard platform error envelope:

{
  "result": false,
  "error": {
    "code": 1605,
    "text": "Error message",
    "documentation_url": "https://api.fast.io/llms.txt",
    "resource": "GET /current/oauth/authorize/"
  }
}