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
• A connection's owner can replace its whole access grant — scopes and, optionally, a per-place tool restriction — at any time via PUT /current/oauth/sessions/{session_id}/grant/, without revoking and reconnecting

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, or none listed in token_endpoint_auth_methods_supported (either way the client is treated as a public client: no token-endpoint client authentication, PKCE S256 required for the code exchange)
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. 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.

What Happens to API Calls After Revocation

A connection does not merely stop working silently — its next use after revocation is a distinguishable, documented response:

• Revoked connection, next call: refused with 401, error.code 189723, error.params.reason: "oauth_session_revoked". This means "reconnect, don't retry" — the connection is gone for good.
• Connection status genuinely could not be checked at that moment: refused with 503, error.code 155326, error.params.reason: "oauth_session_unavailable". This means "retry shortly" — the connection may still be valid.

Every response made using an OAuth connection's token also carries an x-ve-grant-revision response header, set to the grant_revision the request was evaluated under. A client can compare this against the last value it saw to detect that the grant changed (narrowed, widened, or had its tools restricted) without polling GET /current/oauth/sessions/{session_id}/.

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.

Query Parameters:

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

# Filtered to one workspace
curl -X GET "https://api.fast.io/current/oauth/sessions/?workspace_id=1234567890123456789" \
  -H "Authorization: Bearer {jwt_token}"

Response (200 OK):

{
  "result": true,
  "sessions": [
    {
      "session_id": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
      "client_id": "my-app",
      "client_name": "My App",
      "scopes": "[\"workspace:1234567890123456789:rw\"]",
      "scopes_detail": [
        {
          "entity_type": "workspace",
          "entity_id": "1234567890123456789",
          "access_mode": "rw",
          "admin": false,
          "tools": ["read", "write", "comment", "delete", "share"],
          "can_grant": "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,
      "grant_revision": 3,
      "live_grant": true,
      "tools": {"workspace:1234567890123456789": ["read", "write", "comment", "delete", "share"]},
      "tool_policy": null,
      "grant_edit": "replace",
      "tool_enforcement": true,
      "reach": "places",
      "via": "workspace",
      "partial": false
    }
  ],
  "count": 1,
  "filtered_by": {"workspace_id": "1234567890123456789"}
}

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",
    "client_name": "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), including scopes_detail, grant_revision, live_grant, tools, tool_policy, grant_edit, tool_enforcement and reach. via and partial are omitted here — they only appear when listing sessions filtered by workspace_id.

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 — PATCH cannot widen. To widen a connection, the signed-in user replaces its grant with PUT /current/oauth/sessions/{session_id}/grant/. 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 applies on the connection's next request; an access token issued before this capability was released picks it up at its next refresh instead.

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",
    "client_name": "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
  }
}

The response carries the same additional fields as the list response above (scopes_detail, grant_revision, live_grant, tools, tool_policy, grant_edit, tool_enforcement, reach). Narrowing scopes here increments grant_revision, the same as a PUT .../grant/ replacement. A narrowing also tidies the connection's saved tool limits, in the same write: a limit that no longer applies anywhere the narrower grant reaches is removed, and nothing else changes, so the tools in force at a place can only shrink with its access mode. A limit on a place that left the grant is KEPT as an ancestor limit while a place the grant still reaches inherits it (for example a workspace limit, after the workspace is removed but a share inside it stays granted), so the share keeps its limit. A PATCH is never refused because of tool limits. When anything was removed or cut back, the response also carries tool_policy_pruned: an array of the affected place keys (for example ["workspace:1234567890123456789"]); it is absent otherwise.

Error Responses:

PUT /current/oauth/sessions/{session_id}/grant/

Replace the whole access grant of a specific OAuth connection — the granted scopes and, optionally, a per-place tools restriction. Unlike PATCH above, which can only narrow, this endpoint can widen OR narrow, bounded by what the signed-in user holds right now. The session must belong to the authenticated user and must not be revoked.

Path Parameters:

Body Parameters:

Default tool set by access mode (used for any place with no tools entry):

tools constraints:

• Every list must include read.
• A place's tools may not exceed what that place's access mode would allow — admin requires rwa at that place.
• Each key must correspond to a place covered by scopes — a granted entity, or a place a wildcard scope covers — or be an ancestor key: a place that is not itself granted but that a granted place inherits from (a workspace containing a granted share, say). An ancestor key needs read; its tools are not capped by an access mode of its own, because each place that inherits it is capped by that place's own access mode.
• An organization-level place cannot take a tools entry at all — restriction is per workspace/share/user, never per org.
• Organization-level actions are held to the connection's user:* tool limits when its tools has a user:* entry. Creating a workspace or joining needs write and leaving the organization needs delete. Inviting, removing or updating members follows the organization's member-management setting: write (delete to remove) when members may manage members, admin when that is limited to administrators or the owner. Administration actions (organization settings, billing, single sign-on, closing it, signing a member out, transferring a member's access) need admin. Without a user:* entry, the access mode of the organization grant alone decides. The tools reported for an organization entry follow the same rule.

Actions that need particular tools:

• Editing AI memory needs write (Create & edit). Memory writes the AI agent makes in a chat started through the connection follow the connection's live limits, the same as its other actions; with write off the agent cannot write memory but keeps the connection's other actions there (for example commenting).
• Connecting an ongoing cloud-sync source into a workspace needs delete as well as write (Create & edit) at that workspace, because an ongoing sync mirrors deletions made at the provider into the workspace. A two-way source (access_mode read_write) — creating one, or switching a source to it — also needs share, because it sends the workspace's files out to the provider and keeps doing so after the connection is revoked.

What replacing a grant may and may not do:

• The new grant is capped by what the signed-in user CURRENTLY holds, which may be wider OR narrower than the connection's existing grant. Requesting rwa (administrative) access at a place is only possible where the user is currently an administrator of that place.
• Account-settings access cannot be newly added here. If the connection already carries it, this endpoint can keep it; it cannot grant it to a connection that does not already have it.
• Only the connection's own owner may call this, with their own signed-in session — a call made with an OAuth or API-key credential is refused with 403.
• A connection that is not the caller's own answers 404 (never reveals whether it exists).
• An already-revoked connection is refused with 406.
• A retried identical request that already succeeded once simply returns 200 again — safe to retry after a timeout or a dropped response.
• Takes effect on the connection's very next API call — no token refresh required. An access token issued before this capability was released picks the change up at its next refresh instead, within an hour.

curl -X PUT "https://api.fast.io/current/oauth/sessions/a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4/grant/" \
  -H "Authorization: Bearer {jwt_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "scopes": ["workspace:1234567890123456789:rw"],
    "tools": {"workspace:1234567890123456789": ["read", "write", "comment"]},
    "expected_revision": 2
  }'

Response (200 OK):

{
  "result": true,
  "session": {
    "session_id": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
    "client_id": "my-app",
    "client_name": "My App",
    "scopes": "[\"workspace:1234567890123456789:rw\"]",
    "scopes_detail": [
      {
        "entity_type": "workspace",
        "entity_id": "1234567890123456789",
        "access_mode": "rw",
        "admin": false,
        "tools": ["read", "write", "comment"],
        "can_grant": "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,
    "grant_revision": 3,
    "live_grant": true,
    "tools": {"workspace:1234567890123456789": ["read", "write", "comment"]},
    "tool_policy": {"workspace:1234567890123456789": ["read", "write", "comment"]},
    "grant_edit": "replace",
    "tool_enforcement": true,
    "reach": "places"
  }
}

Field meanings are the same as the list response under GET /current/oauth/sessions/ above.

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.

Restricted Connections

A restricted connection is a connection that has per-place tools set (its tools are narrower than the access mode's default tool set somewhere; GET /current/auth/scopes/ then reports tool_enforcement: true). When a client calls the API using a restricted connection's own token:

• GET /current/oauth/sessions/ returns only that one connection, never the user's other connections.
• DELETE /current/oauth/sessions/ (revoke all) is refused with 403.
• Creating, updating or regenerating an API key (POST /current/user/auth/key/...) is refused with 403.
• Approving a new OAuth authorization (POST /current/oauth/authorize/) is refused with 403.
• Reading, revoking or editing one of the user's OTHER connections by id (/current/oauth/sessions/{session_id}/): GET answers 404, DELETE and PATCH are refused with 403. Its own session can still be read, renamed, narrowed and revoked.
• Creating a workspace service account, issuing one of its keys, enabling one, or changing one (/current/workspace/{workspace_id}/service_accounts/...) is refused with 403.
• Issuing an organization SCIM token, configuring the organization audit stream or rotating its secret is refused with 403.
• Starting a move of the organization's files onto its own encryption key, or a rotation of that key (POST /current/org/{org_id}/storage/encryption/migrate/ and /rotate/), is refused with 403. Reading the encryption status is allowed.
• Changing the organization's single sign-on settings — saving or removing the configuration, or adding, verifying or removing a sign-on domain — is refused with 403. Reading the settings is allowed.

Each of these refusals carries error.params = {"reason": "tool_disabled", "tool": "admin", "place": {"type": "user", "id": "*", "name": null}}.

All of these are refused for the same reason: a tool-restricted connection cannot mint or widen a credential, change who can sign in, administer the account's other connections, or otherwise use itself to gain broader standing than it was granted. A credential it minted would carry no tool limits and would keep working after the connection is revoked. A plain, unrestricted connection is unaffected by any of this.

AI chats started through a connection follow that connection's live limits on every request. When an agent using a connection's token starts or continues an AI chat, every action the AI agent takes for that chat is bounded by the connection's CURRENT access: its tool limits, its access modes, the places it still covers (a place the connection no longer covers is refused), and its revocation (once the connection is revoked, the AI agent's next action is refused). A limit set or tightened while a chat is in progress applies to the agent's next action. For a connection without tool limits, the AI agent behaves as before, within the connection's access.

More generally, any API call made with a tool-restricted connection is refused with 403 when the specific tool it needs is not in that connection's allowed list for the relevant place. The error has error.code 116782 and error.params = {"reason": "tool_disabled", "tool": "<tool>", "place": {"type": "<entity type>", "id": "<entity id>", "name": "<display name or null>"}}, e.g. {"reason": "tool_disabled", "tool": "delete", "place": {"type": "workspace", "id": "1234567890123456789", "name": "Marketing"}}. Branch on error.params.reason, not on the code.

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/"
  }
}