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

Overview

Fastio 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 are long-lived
• 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 — email-and-password users sign in on the Fastio sign-in page (login.fast.io) during the browser step
• Native clients may use a loopback redirect URI on 127.0.0.1 with any port (RFC 8252); headless clients can use display_code=true (copy-paste code)
• 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://go.fast.io",
  "authorization_endpoint": "https://go.fast.io/api/current/oauth/authorize",
  "token_endpoint": "https://go.fast.io/api/current/oauth/token",
  "revocation_endpoint": "https://go.fast.io/api/current/oauth/revoke",
  "registration_endpoint": "https://go.fast.io/api/current/oauth/register",
  "response_types_supported": ["code"],
  "grant_types_supported": ["authorization_code", "refresh_token"],
  "code_challenge_methods_supported": ["S256"],
  "token_endpoint_auth_methods_supported": ["none"],
  "scopes_supported": ["user", "org", "workspace", "all_orgs", "all_workspaces", "all_shares", "all_sign_envelopes"],
  "access_modes_supported": ["r", "rw", "rwa"],
  "client_id_metadata_document_supported": true,
  "resource_indicators_supported": true,
  "service_documentation": "https://go.fast.io/api/current/llms/"
}

Response Fields:

Clients validating access_modes_supported against {r, rw} must accept rwa. The list now carries a third mode — read, write and administer — so a client that rejects unknown values will fail against it. scopes_supported is unchanged: userdetails is an entity type inside a credential's scope list, never a scope type, and is never advertised here.

Error Responses:

Reading the error tables: the four-digit 16xx/17xx values below are HTTP-status classes, not error.code. The error.code a client actually receives is assigned per endpoint, so use the HTTP status as the gate and a documented error.code — five or six digits, plus the 9661-9669 family — only as a refinement. A 16xx value identifies the status class — useful for telling which kind of failure occurred — but comparing one against error.code will never match. Five- and six-digit codes (and the 9661-9669 family) are real error.code values. If you widen a check from a specific code to a status, widen what you assert with it — a status covers failures the narrower code did not, so a message written for that one code becomes a confident falsehood on the rest.

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

{
  "result": true,
  "resource": "https://mcp.fast.io/mcp",
  "authorization_servers": ["https://go.fast.io"],
  "bearer_methods_supported": ["header"],
  "scopes_supported": ["user", "org", "workspace", "all_orgs", "all_workspaces", "all_shares", "all_sign_envelopes"]
}

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,
  "client_id": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
  "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": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
  "registration_client_uri": "https://go.fast.io/api/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 a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6" \
  -d '{
    "client_id": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
    "client_name": "My Updated MCP Client",
    "redirect_uris": ["http://localhost:8080/callback"]
  }'

Response (200 OK):

{
  "result": true,
  "client_id": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
  "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, with 1–10 entries that each pass the same redirect-URI rules as dynamic registration
   • 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/?response_type=code&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):

These seven are the complete offered set — they match the scopes_supported array in the authorization-server metadata (GET /.well-known/oauth-authorization-server). Request one of these named values, or omit scope for the default user. Values are case-sensitive. Words outside this set are ignored only if they are the OpenID Connect words openid, profile, email or offline_access; a request made only of those is treated like an omitted scope (the default user type at the consented access mode). A scope that names none of the seven otherwise is refused with a 406 input error (invalid_scope); the one exception is the retired all_workflows value, which is accepted here but never grants anything (consent fails). If several recognised values are sent space-separated, the broadest one is used. Always read scopes in the token response for what was actually granted.

access_mode and account_settings are ceilings recorded with the authorization request. They are set here, on the initiate request, and the consent step (POST /current/oauth/authorize/) can only narrow them. access_mode bounds the access mode of every granted scope; account_settings decides whether account-settings access may be granted at all. A client that never sends them cannot obtain administration (rwa) or account settings through OAuth — administration is opt-in on a request the client made explicitly, and the consent screen never offers it unprompted.

Retired scope — all_workflows: no longer offered. The Workflows feature has been removed, so all_workflows is deliberately omitted from scopes_supported and must not be requested. The authorization server retains it only as a fail-closed tombstone, so a pre-existing token that still carries it resolves to nothing rather than erroring — it is not a capability you can request. (This is why the offered set is the seven above, not eight.)

# 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={auth_request_id}

Response (response_format=json — 200 OK):

{
  "result": true,
  "auth_request_id": "{auth_request_id}",
  "client_name": "My App",
  "scope": "user",
  "login_url": "https://go.fast.io/connect?auth_request_id={auth_request_id}"
}

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:

Consent rules — scopes, access mode and account settings:

• access_mode may only be narrower than the value stored at initiate. Omit it to take the stored value (rw when the initiate request did not send one). A wider value is refused with 403 10768 (error.params.reason: access_mode_exceeds_initiate); an unrecognised value is 406 161579.
• scopes, when supplied, must be a non-empty JSON list. [], {}, "", a scalar, a nested array or malformed JSON is refused with 406 168998 (or 128552 when it parses to nothing usable).
• When scopes is omitted, scope=org and scope=workspace now require a selection — 406 121987, "The scopes parameter is required for this authorization request." The wildcard scope types (user, all_orgs, all_workspaces, all_shares, all_sign_envelopes) resolve to their own default set at the consented access mode, and a scope made only of ignored OpenID Connect words resolves to the user type (any other unrecognised scope is refused at initiate).
• For scope=org and scope=workspace, an explicit scopes list may narrow within the initiated scope type but may not name a different entity type (406 149822). A scope=user authorization is the whole account, so its list may name any entity type the human holds.
• Every granted scope is capped at the stored access mode; a broader one is refused with 403 10768 / access_mode_exceeds_initiate.
• A client-supplied userdetails scope is always refused (same code and reason). Clients must never put userdetails:*:rw in scopes themselves.
• account_settings=1 appends userdetails:*:rw server-side, and only when the initiate request carried account_settings=1; otherwise the consent is refused with 403 10768 / access_mode_exceeds_initiate.
• Each authorization request can be consented to once. The request is claimed atomically just before the code is issued, so a second — or concurrent — consent for the same auth_request_id is refused with 404 ("The authorization request is invalid or has expired."), and GET /current/oauth/authorize/info/ then reports valid: false. A consent refused by one of the checks in this list does not use the request up.
• The consent request itself must be made with an account-level credential — a narrowed credential is refused with 403 10175 — and the granted set may not exceed that credential (403 10768 / scope_exceeds_issuer).
• The 20-scope cap still applies after the server-side append — 406 157349.
• The granted scopes are checked against the governing org's credential_policy, when the human's organization has configured one (Enterprise plan). A scope whose mode exceeds the org's configured ceiling, or whose entity type the org's policy does not allow, is refused with 403 and error.params.reason credential_policy_mode or credential_policy_scope. Branch on the reason, never on the numeric code. This runs as soon as the granted scopes have been validated — after the account-level-credential and access_mode checks, but before the per-scope ceiling, account_settings, 20-scope-cap and scope-exceeds-issuer checks above — against each granted scope's own owning org — see Org Credential Policy in the Auth reference. Unlike the other consent-time checks, this one is also re-evaluated on every later request the resulting token makes; a working OAuth grant can start failing this way if the org tightens its policy after consent.

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={auth_request_id}"

Response (200 OK):

{
  "result": true,
  "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={auth_request_id}"

Response (valid request — 200 OK):

{
  "result": true,
  "valid": true,
  "client_name": "My App",
  "scope": "user",
  "agent_name": "My MCP Agent",
  "redirect_mode": "redirect",
  "redirect_uri": "http://localhost:8080/callback",
  "resource": "https://mcp.fast.io/mcp",
  "access_mode": "rw",
  "account_settings": false
}

resource is the RFC 8707 resource indicator the client supplied at initiate (or null), access_mode is the requested access mode ("r", "rw" or "rwa", or null when the client did not supply one), and account_settings is a boolean that is always present. All three are returned server-authoritatively from the stored authorization request, so consent screens can render them without trusting URL parameters.

Show the account-settings toggle only when account_settings is true, and default it to off. When it is false the authorization was not initiated for account settings, and consent cannot grant them.

Response (invalid or expired — 200 OK):

{
  "result": true,
  "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 (the login_url from JSON mode, or the 302 target), signs in (supports SSO; email-and-password users sign in on the Fastio sign-in page, which also handles 2FA), 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" or "display_code")

Loopback redirect URIs (native apps, RFC 8252). A client registered with an http loopback redirect URI such as http://127.0.0.1:8080/callback may send the same URI with any port at authorize time, so a CLI or desktop app can listen on an ephemeral port. Only the port may differ — scheme, host, path and query must match the registered URI exactly, and localhost and 127.0.0.1 are different hosts. The token request must send exactly the redirect_uri used at authorize, including the port.

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": "{refresh_token}",
  "scope": "org",
  "scopes": "[\"org:3814271023567182934:rw\",\"org:3829104758203948571:rw\"]",
  "agent_name": "My MCP Agent"
}

Response Fields:

scope versus scopes. scope (singular) is a single scope-type word summarising the grant; scopes (plural) is a JSON-encoded string listing the granted entity scopes. Persist scopes, not scope.

scopes is now returned for every grant, including a plain scope=user grant that previously carried no list — such a grant is stored explicitly as ["user:*:rw"]. Clients must not treat a missing scopes as “this is a full session”, and must not branch on auth_type === "jwt_v1": those grants now report jwt_v2 at introspection.

This response carries no admin and no legacy field — derive administrative capability from GET /current/auth/scopes/.

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={refresh_token}&client_id=my-app"

Response (200 OK — bare JSON): Same format as authorization code exchange. Returns a new access_token. The refresh_token is long-lived and is returned unchanged (no per-refresh rotation).

Refresh narrows a demoted administrative grant. A grant naming a concrete entity at rwa whose human is no longer an administrator of it comes back as rw, and the response's scopes echoes the narrowed set — which is then what the session holds. Wildcard rwa grants are never narrowed this way; they are capped live on every request against the human's role. Losing access to an entity entirely still revokes, as before.

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={refresh_token}"

Response (200 OK):

{
  "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 refreshes.

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,
  "sessions": [
    {
      "session_id": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
      "client_id": "my-app",
      "scopes": "[\"org:3814271023567182934:rw\"]",
      "agent_name": "My MCP Agent",
      "device_name": "Chrome on macOS",
      "device_type": "desktop",
      "ip_address": "203.0.113.42",
      "last_used": "2026-01-22 14:00:00 UTC",
      "created": "2026-01-21 14:00:00 UTC",
      "expires": "2036-01-21 14:00:00 UTC",
      "admin": false,
      "legacy": false,
      "country": "US",
      "last_ip": "203.0.113.42",
      "last_country": "US",
      "mcp": false
    }
  ],
  "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,
  "session": {
    "session_id": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
    "client_id": "my-app",
    "scopes": "[\"org:3814271023567182934:rw\"]",
    "agent_name": "My MCP Agent",
    "device_name": "Chrome on macOS",
    "device_type": "desktop",
    "ip_address": "203.0.113.42",
    "last_used": "2026-01-22 14:00:00 UTC",
    "created": "2026-01-21 14:00:00 UTC",
    "expires": "2036-01-21 14:00:00 UTC",
    "admin": false,
    "legacy": false,
    "country": "US",
    "last_ip": "203.0.113.42",
    "last_country": "US",
    "mcp": false
  }
}

Field meanings are the same as the list response above (country = creation IP, never updated; last_ip/last_country = last refresh, written periodically, not on every refresh; mcp = whether this grant's audience is the Fastio MCP server).

Error Responses:

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

Update the device_name, agent_name and/or scopes 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, agent_name or scopes must be provided, so a scopes-only request is valid.

Narrowing only — there is no widening path. Submitted scopes are checked against the session's current scopes and against the credential making the request; a broader set is refused with 403 and 10768 (error.params.reason: scope_exceeds_issuer). An empty list ([]) — or a value that does not parse as a list of scope strings — is refused with 406 136396 — to end a session entirely use DELETE /current/oauth/sessions/{session_id}/. A narrowing takes effect for the access token at the next refresh.

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,
  "session": {
    "session_id": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
    "client_id": "my-app",
    "scopes": "[\"org:3814271023567182934:rw\"]",
    "agent_name": "My MCP Agent",
    "device_name": "My Work Laptop",
    "device_type": "desktop",
    "ip_address": "203.0.113.42",
    "last_used": "2026-01-22 14:00:00 UTC",
    "created": "2026-01-21 14:00:00 UTC",
    "expires": "2036-01-21 14:00:00 UTC",
    "admin": false,
    "legacy": false,
    "country": "US",
    "last_ip": "203.0.113.42",
    "last_country": "US",
    "mcp": false
  }
}

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,
  "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,
  "message": "All sessions have been revoked."
}

Or when exclude_current is used:

{
  "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,
  "auth_type": "jwt_v2",
  "scopes": ["org:3814271023567182934:rw", "org:3829104758203948571:rw"],
  "scopes_detail": [
    {
      "entity_type": "org",
      "entity_id": "3814271023567182934",
      "access_mode": "rw",
      "admin": false,
      "name": "Acme Corp",
      "domain": "acme"
    },
    {
      "entity_type": "org",
      "entity_id": "3829104758203948571",
      "access_mode": "rw",
      "admin": false,
      "name": "Beta Inc",
      "domain": "beta"
    }
  ],
  "is_agent": true,
  "agent_name": "My MCP Agent",
  "full_access": false,
  "admin": false,
  "legacy": false
}

Response (200 OK — API-key auth with scopes and expiration):

{
  "result": true,
  "auth_type": "api_key_scoped",
  "scopes": ["org:3814271023567182934:rw"],
  "scopes_detail": [
    {
      "entity_type": "org",
      "entity_id": "3814271023567182934",
      "access_mode": "rw",
      "admin": false,
      "name": "Acme Corp",
      "domain": "acme"
    }
  ],
  "is_agent": true,
  "agent_name": "CI Pipeline",
  "full_access": false,
  "admin": false,
  "legacy": false,
  "expires": "2026-12-31 23:59:59 UTC"
}

Response Fields:

Scope Detail Fields:

Each entry in scopes_detail contains entity-specific fields:

Labels follow the access mode: user:*:rw renders as "Full Access", user:*:rwa as "Full Access (Admin)", user:*:r as "Entire account (Read Only)" and userdetails:*:rw as "Account settings"; other wildcards render in the same style, e.g. "All Organizations (Read/Write/Admin)".

How the flags combine:

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
   (programmatic clients add &response_format=json and open the returned login_url verbatim)
   -> 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, with display_code=true, displayed on screen for the 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": "4f9a2c...",
     "scope": "user"
   }

7. CLIENT -> API: Use access token for requests
   GET /current/user/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=4f9a2c...
   &client_id=my-app

   -> Returns a new access_token; the same refresh_token is returned unchanged

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

   token=4f9a2c...

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": 116775,
    "text": "The client_id is invalid or not found.",
    "documentation_url": "https://api.fast.io/llms.txt",
    "resource": "GET /current/oauth/authorize/"
  }
}