docs: clarify OAuth revocation behavior, disable_vk_identity flag, and token lifetime semantics

[Pratham-Mishra04]

Summary

This PR clarifies and corrects documentation around OAuth token lifecycle, revocation behavior, and the new disable_vk_identity configuration option. It also fixes inaccurate descriptions of how Bifrost handles upstream OAuth revocation, access token validation, and the distinction between revoking a grant versus deleting the bound identity.

Changes

• Added revoked as a documented OAuth config status value, clarifying that the config row is retained with no live token after a DELETE call.
• Corrected the DELETE endpoint description: Bifrost does not call the upstream provider's revocation endpoint — it only deletes the stored token locally and marks the config revoked. Users must revoke at the provider's dashboard if upstream invalidation is needed.
• Clarified that access token refresh happens lazily on next use after expiration, not proactively before expiration.
• Updated the per-user OAuth note to clearly separate upstream per-user OAuth (tokens held for upstream MCP services) from Bifrost acting as an OAuth 2.1 Authorization Server for inbound /mcp clients, with a cross-reference to the Gateway Authentication page.
• Expanded the Token Lifetime & Revocation section to document:
  • The in-memory identity cache used during access token validation and its fallback behavior.
  • The distinction between revoking a grant (stops refresh, but existing access token lives out its TTL) versus deleting the bound virtual key or user (also rejects the already-issued access token on its next request).
  • The behavior of disable_vk_identity: rejects all virtual-key-mode grants at /mcp and on refresh, forcing re-authentication as a user.
• Added disable_vk_identity to the OpenAPI config schema with a description of its scope and conditions.
• Updated RevokeOAuth2RefreshTokensByMode comment to be more precise about its purpose as a bulk-revoke utility.
• Corrected internal comments in OAuth2ServerConfig to reference the OAuth Grants UI (not "Connected Clients UI") and DisableVKIdentity (not EnforceAuthOnInference) as the vk-mode revocation path.
• Added a note explaining why revoked grants leave short-lived access tokens usable until expiry, and why this is an intentional trade-off.

Type of change

• Bug fix
• Feature
• Refactor
• Documentation
• Chore/CI

Affected areas

• Core (Go)
• Transports (HTTP)
• Providers/Integrations
• Plugins
• UI (React)
• Docs

How to test

Review the updated documentation pages for accuracy against the actual Bifrost OAuth implementation:

• docs/mcp/auth/oauth.mdx — verify DELETE behavior and status values match implementation.
• docs/mcp/auth/per-user-oauth.mdx — verify the note correctly distinguishes upstream vs. inbound OAuth.
• docs/mcp/gateway-auth.mdx — verify token lifetime, revocation, and disable_vk_identity descriptions match behavior.
• docs/openapi/schemas/management/config.yaml — verify disable_vk_identity schema matches the Go struct definition.

Breaking changes

• Yes
• No

Security considerations

The documentation now explicitly states that Bifrost does not call upstream OAuth provider revocation endpoints on DELETE. Operators who assumed upstream tokens were being invalidated must be made aware they need to revoke tokens directly at the provider's dashboard. The updated revocation lifecycle documentation also clarifies the security window left by short-lived access tokens after a grant revoke, and recommends lowering access_token_ttl for tighter control.

Checklist

• I read docs/contributing/README.md and followed the guidelines
• I added/updated tests where appropriate
• I updated documentation where needed
• I verified builds succeed (Go and UI)
• I verified the CI pipeline passes locally if applicable

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 063123b1-3516-418e-bb55-8a8de5dd536a

📥 Commits

Reviewing files that changed from the base of the PR and between 6aa0f0d and 145e756.

📒 Files selected for processing (6)

• docs/mcp/auth/oauth.mdx
• docs/mcp/auth/per-user-oauth.mdx
• docs/mcp/gateway-auth.mdx
• docs/openapi/schemas/management/config.yaml
• framework/configstore/rdb.go
• framework/configstore/tables/mcpoauth2server.go

---

📝 Walkthrough

Summary by CodeRabbit

• Documentation

  • Clarified OAuth token behavior, including refresh timing, revocation status, and how revoked tokens are handled.
  • Improved MCP authentication docs to better separate upstream per-user OAuth from inbound client authentication.
  • Expanded gateway auth guidance with clearer token validation, revocation, and identity-check behavior.

• New Features

  • Added a new configuration option to disable virtual-key identity in OAuth flows, with documented effects on consent, refresh, and access to MCP.

Walkthrough

Adds disable_vk_identity boolean field to oauth2_server_config OpenAPI schema. Updates gateway auth, upstream OAuth, and per-user OAuth documentation to clarify access-token validation semantics, revocation behavior, token status values, and the distinction between upstream and inbound OAuth flows.

Changes

OAuth Config Field and Documentation Updates

Layer / File(s)	Summary
disable_vk_identity schema and code comments docs/openapi/schemas/management/config.yaml, framework/configstore/rdb.go, framework/configstore/tables/mcpoauth2server.go	Adds disable_vk_identity boolean (default false) to oauth2_server_config; updates inline comments to add it as a refresh-token invalidation condition and clarifies bf_mode parameter description.
Gateway auth token lifetime and revocation docs docs/mcp/gateway-auth.mdx	Rewrites Token Lifetime & Revocation section: access tokens validated per /mcp request with identity-active check and caching; revoke stops refresh rotation without immediately invalidating access tokens; disable_vk_identity blocks vk-mode grants immediately; deleting a virtual key/user rejects subsequent requests.
Upstream OAuth status, revoke, and per-user note docs/mcp/auth/oauth.mdx, docs/mcp/auth/per-user-oauth.mdx	Adds revoked status to OAuth config states; corrects automatic refresh timing to "on next use after expiration"; rewrites Revoke section to state no upstream revocation endpoint is called; updates per-user OAuth note to distinguish upstream token holding from inbound OAuth 2.1 Authorization Server functionality.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Suggested reviewers

• akshaydeo

Poem

🐇 A token revoked, a status newfound,
disable_vk_identity — what a sound!
Refresh on next use, not a moment before,
The gateway now checks identity once more.
Docs rewritten, the rabbit hops clear — 🌟

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch 06-30-fix_doc_fixes

Warning

There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure.

🔧 golangci-lint (2.12.2)

level=error msg="[linters_context] typechecking error: pattern ./...: directory prefix . does not contain main module or its selected dependencies"

---

_{Comment @coderabbitai help to get the list of available commands.}

[Pratham-Mishra04]

• docs: clarify OAuth revocation behavior, disable_vk_identity flag, and token lifetime semantics #4807 👈 (View in Graphite)
• feat: revoke VK-mode OAuth2 grants on VK deletion and add user-liveness checks at refresh and request time #4806
• feat: scope pre-authenticated user requests to their representative virtual key in headers/both auth modes #4784
• feat: add virtualKeysByID secondary index and cache signing key + VK lookups on /mcp JWT auth path #4783
• feat: push OAuth2 sessions filtering and pagination to SQL with total count #4775
• fix: make MCP sessions table scrollable with sticky header and improved pagination UI #4774
• feat: add interactive MCP test client with header and OAuth auth support #4773
• fix: exclude terminal-status oauth configs from expiring token refresh query #4754
• feat: add disable_vk_identity to suppress virtual-key identity in OAuth consent flow #4751
• refactor: move Circuit Breaker above Pricing Overrides in sidebar, update icons, and fix template literal formatting #4750
• tests: add MCP auth e2e collection covering discovery, credential matrix, OAuth issuance, refresh rotation, revocation window, and runtime mode flip #4525 : 1 other dependent PR (#4744 )
• tests: add MCP auth mode e2e collection and Newman runner for headers/both/oauth #4524
• tests: add OAuth2 issuance, JWT verification, consent, discovery, sessions, and MCP auth unit tests #4523
• feat: add mcp_server_auth_mode and OAuth 2.1 gateway auth docs with gateway-auth page #4522
• ui: add OAuth Grants page and identity exact-match filter for MCP sessions #4511
• ui: add OAuth2 consent page and MCP server auth mode settings #4510
• feat: add OAuth2 session listing, revocation, family-revocation, VK liveness check, and sweep worker #4509
• feat: add JWT Bearer authentication path for /mcp with session validation and context injection #4508
• feat: add OAuth2ConsentHandler with VK, session, and user identity resolution modes #4507
• feat: add OAuth2 issuance endpoints (DCR, authorize, token) with PKCE and refresh token rotation #4506
• feat: add OAuth2 AS discovery endpoints, signing key management, and MCPServerAuthMode config #4505
• refactor: rename MCP handler files to remove underscores and drop redundant prefixes #4747
• dev

This stack of pull requests is managed by Graphite. Learn more about stacking.

[CLAassistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.
_{You have signed the CLA already but the status is still pending? Let us recheck it.}

[Pratham-Mishra04]

Merge activity

• Jun 30, 1:53 PM UTC: A user started a stack merge that includes this pull request via Graphite.
• Jun 30, 2:56 PM UTC: Graphite rebased this pull request as part of a merge.
• Jun 30, 2:57 PM UTC: @Pratham-Mishra04 merged this pull request with Graphite.

[greptile-apps]

Confidence Score: 5/5

Safe to merge — documentation and comment corrections only, with no changes to runtime logic.

All changes are documentation, OpenAPI schema descriptions, and Go source comments. The factual claims were verified against the implementation: the DELETE handler in framework/oauth2/main.go confirms no upstream revocation endpoint is called, and the DisableVKIdentity handler logic in mcpserver.go and config.go matches the documented behavior. The only gap found is that disable_vk_identity is missing from the config field reference table in gateway-auth.mdx, which is a documentation completeness issue rather than an accuracy problem.

docs/mcp/gateway-auth.mdx — the Configuration section's field table does not yet list disable_vk_identity alongside the other oauth2_server_config fields.

Important Files Changed

Filename	Overview
docs/mcp/auth/oauth.mdx	Adds revoked status value, fixes DELETE description to accurately state that Bifrost does not call the upstream revocation endpoint (confirmed in framework/oauth2/main.go), and corrects the refresh description from proactive to lazy.
docs/mcp/auth/per-user-oauth.mdx	Replaces inaccurate 'Bifrost is not an OAuth AS' note with accurate distinction between upstream per-user OAuth and inbound OAuth 2.1 AS flows, with a cross-reference to gateway-auth.
docs/mcp/gateway-auth.mdx	Expands Token Lifetime & Revocation section with in-memory identity cache behavior, grant-revoke vs. delete-identity distinction, and disable_vk_identity semantics; disable_vk_identity is missing from the config field reference table in the Configuration section.
docs/openapi/schemas/management/config.yaml	Adds disable_vk_identity to the OAuth2ServerConfig schema with an accurate description matching the Go struct and handler validation logic.
framework/configstore/rdb.go	Comment update only: RevokeOAuth2RefreshTokensByMode comment rewritten to describe it as a general bulk-revoke utility rather than tied to EnforceAuthOnInference.
framework/configstore/tables/mcpoauth2server.go	Internal comment corrections: updates revocation path list to reference OAuth Grants UI and DisableVKIdentity instead of stale Connected Clients UI and EnforceAuthOnInference references.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[Client holds access token] --> B{Grant revoked?}
    B -- No --> C{Identity active?}
    B -- Yes --> D[Refresh denied]
    D --> E[Token usable until TTL expires]
    C -- Deleted or deactivated --> G[Identity check fails]
    G --> H[Token rejected immediately]
    C -- Active --> I[Request succeeds]
    subgraph Bulk cutoffs
      J[disable_vk_identity] --> L[vk-mode grants rejected at /mcp]
      N[enforce_auth_on_inference] --> O[Session tokens blocked at /mcp]
    end

Loading

%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
flowchart TD
    A[Client holds access token] --> B{Grant revoked?}
    B -- No --> C{Identity active?}
    B -- Yes --> D[Refresh denied]
    D --> E[Token usable until TTL expires]
    C -- Deleted or deactivated --> G[Identity check fails]
    G --> H[Token rejected immediately]
    C -- Active --> I[Request succeeds]
    subgraph Bulk cutoffs
      J[disable_vk_identity] --> L[vk-mode grants rejected at /mcp]
      N[enforce_auth_on_inference] --> O[Session tokens blocked at /mcp]
    end

Loading

_{Reviews (2): Last reviewed commit: "fix: doc fixes" | Re-trigger Greptile}