Gateway Authentication

​

Overview

• Header credentials — a virtual key, API key, or session token sent as a request header. Simple to script, ideal for backend and machine-to-machine use.
• OAuth 2.1 — Bifrost acts as an OAuth authorization server, and the client connects through a browser consent flow, receiving a short-lived JWT. Ideal for interactive clients like Claude Desktop, Claude Code, or Cursor, where pasting a raw key into client config is awkward.

​

Authentication Modes

• headers — /mcp accepts header credentials only. The OAuth surface and .well-known discovery endpoints are not served.
• both — /mcp accepts header credentials and Bifrost-issued JWTs. Discovery is served so OAuth clients can connect.
• oauth — /mcp accepts Bifrost-issued JWTs only; header credentials are rejected.

​

How the OAuth Connect Flow Works

• Protected resource metadata (RFC 9728) — the 401 response points clients at the discovery documents.
• Dynamic Client Registration (RFC 7591) — clients self-register; no manual client setup.
• PKCE (S256) — public clients authenticate without a shared secret.
• Resource indicators (RFC 8707) — tokens are bound to the /mcp resource via the aud claim.

​

Identity Modes at Consent

• Virtual key carries the same governance (budgets, rate limits, tool scoping) the key already has — the JWT simply represents that key.
• Session is an anonymous identity for development and open deployments. It is unavailable once enforce_auth_on_inference is on.
• User binds the grant to the authenticated person, so per-user upstream tool authorizations unify under one identity.

​

Configuration

curl -X PUT http://localhost:8080/api/config \
  -H "Content-Type: application/json" \
  -d '{
    "client_config": {
      "mcp_server_auth_mode": "both",
      "oauth2_server_config": {
        "issuer_url": "https://bifrost.example.com",
        "auth_code_ttl": 300,
        "access_token_ttl": 600
      }
    }
  }'

{
  "client": {
    "mcp_server_auth_mode": "both",
    "oauth2_server_config": {
      "issuer_url": "https://bifrost.example.com",
      "auth_code_ttl": 300,
      "access_token_ttl": 600
    }
  }
}

​

Connecting a Client

1. The client hits /mcp, gets a 401, and discovers the authorization server.
2. It registers itself and opens a browser to the consent page.
3. The user chooses an identity (virtual key, session, or user).
4. The client receives a token and connects; aggregated tools become available.

​

Managing Grants

​

Token Lifetime & Revocation

• Access tokens are JWTs valid for access_token_ttl (default 600s). On every /mcp request Bifrost validates the JWT — signature, expiry, issuer, and audience — and confirms the bound identity (the virtual key or user) still exists and is active. The identity check reads an in-memory cache, so in the common case it adds no database round-trip (vk-mode falls back to a single store lookup only on a cache miss).
• Refresh tokens rotate on each use and have no fixed expiry. A token is invalidated by rotation, by the bound virtual key or user becoming inactive or deleted, or by an explicit revoke.
• An explicit revoke marks the grant’s refresh-token row revoked, so renewals stop immediately — but it does not remove the bound identity, so the identity check still passes and the already-issued access token keeps working until it expires. Lower access_token_ttl to shorten that window.
• Deleting the bound virtual key or user is stronger than revoking a grant: it revokes the grant immediately and the identity check rejects the grant’s already-issued access token on its next /mcp request, instead of letting it live out its TTL.
• Enabling disable_vk_identity (require identity-provider login) cuts off all virtual-key–mode grants immediately — they are rejected at /mcp and denied on refresh — so those clients must re-authenticate as a user. Only applies in oauth mode with an identity provider configured.
• Enabling enforce_auth_on_inference blocks session-mode (anonymous) tokens at /mcp, but does not delete or invalidate their grants — the grants remain in the database and become valid again if enforcement is later disabled. To remove a session-mode grant permanently, revoke it on the OAuth Grants page.

​

Discovery Endpoints

​

Troubleshooting

​

Discovery returns 404

​

Header credential rejected on /mcp

​

Conflicting credentials on /mcp

​

Client keeps re-opening the browser

​

Token rejected after issuer change

​

Next Steps

• Bifrost as an MCP Gateway — Expose aggregated tools to external MCP clients.
• MCP Sessions — Inspect and manage per-user credentials for upstream servers.
• Virtual Keys — Govern budgets, rate limits, and tool scope for the identities behind grants.