A valid request URL is required to generate request examples{
"status": "pending_oauth",
"message": "<string>",
"oauth_config_id": "<string>",
"flow_id": "<string>",
"authorize_url": "<string>",
"expires_at": "2023-11-07T05:31:56Z",
"mcp_client_id": "<string>",
"complete_url": "<string>",
"status_url": "<string>",
"next_steps": [
"<string>"
],
"registered_client_id": "<string>",
"previous_client_id": "<string>"
}{
"event_id": "<string>",
"type": "<string>",
"is_bifrost_error": true,
"status_code": 123,
"error": {
"type": "<string>",
"code": "<string>",
"message": "<string>",
"param": "<string>",
"event_id": "<string>"
},
"extra_fields": {
"provider": "anthropic",
"model_requested": "<string>",
"request_type": "<string>",
"error_type": "<string>",
"retry_after_ms": 150500
}
}{
"event_id": "<string>",
"type": "<string>",
"is_bifrost_error": true,
"status_code": 123,
"error": {
"type": "<string>",
"code": "<string>",
"message": "<string>",
"param": "<string>",
"event_id": "<string>"
},
"extra_fields": {
"provider": "anthropic",
"model_requested": "<string>",
"request_type": "<string>",
"error_type": "<string>",
"retry_after_ms": 150500
}
}{
"event_id": "<string>",
"type": "<string>",
"is_bifrost_error": true,
"status_code": 123,
"error": {
"type": "<string>",
"code": "<string>",
"message": "<string>",
"param": "<string>",
"event_id": "<string>"
},
"extra_fields": {
"provider": "anthropic",
"model_requested": "<string>",
"request_type": "<string>",
"error_type": "<string>",
"retry_after_ms": 150500
}
}{
"event_id": "<string>",
"type": "<string>",
"is_bifrost_error": true,
"status_code": 123,
"error": {
"type": "<string>",
"code": "<string>",
"message": "<string>",
"param": "<string>",
"event_id": "<string>"
},
"extra_fields": {
"provider": "anthropic",
"model_requested": "<string>",
"request_type": "<string>",
"error_type": "<string>",
"retry_after_ms": 150500
}
}Reauthorize an MCP client against a newly registered OAuth client
Registers a replacement OAuth client (RFC 7591 Dynamic Client Registration) at the config’s registration_url, writes it over the stored credentials, and then runs the same consent flow POST /api/mcp/client//reauthorize runs, against the new client.
This exists for a provider that no longer recognises the client_id it issued, which is common with Dynamic Client Registration because the provider’s client registry is often in memory and does not survive a restart. Once that happens the stored client_id is rejected at the token endpoint on every refresh and at the authorize endpoint on every reauthorization, so plain reauthorize cannot recover the connection.
Replacing the client_id marks every credential stored under the OAuth config needs_reauth and stops using it, since none of them can be refreshed against a client the provider no longer associates them with. It does not revoke access tokens the provider already issued (Bifrost never calls the provider’s revocation endpoint), so those can stay valid at the provider until they expire. For auth_type “per_user_oauth” that includes every end-user credential, not just the retained admin one, and each user must authenticate again. Plain reauthorize leaves end-user credentials untouched; this endpoint does not.
Complete the returned flow exactly like reauthorize’s: open authorize_url in a browser, poll status_url until “authorized”, then POST complete_url.
A valid request URL is required to generate request examples{
"status": "pending_oauth",
"message": "<string>",
"oauth_config_id": "<string>",
"flow_id": "<string>",
"authorize_url": "<string>",
"expires_at": "2023-11-07T05:31:56Z",
"mcp_client_id": "<string>",
"complete_url": "<string>",
"status_url": "<string>",
"next_steps": [
"<string>"
],
"registered_client_id": "<string>",
"previous_client_id": "<string>"
}{
"event_id": "<string>",
"type": "<string>",
"is_bifrost_error": true,
"status_code": 123,
"error": {
"type": "<string>",
"code": "<string>",
"message": "<string>",
"param": "<string>",
"event_id": "<string>"
},
"extra_fields": {
"provider": "anthropic",
"model_requested": "<string>",
"request_type": "<string>",
"error_type": "<string>",
"retry_after_ms": 150500
}
}{
"event_id": "<string>",
"type": "<string>",
"is_bifrost_error": true,
"status_code": 123,
"error": {
"type": "<string>",
"code": "<string>",
"message": "<string>",
"param": "<string>",
"event_id": "<string>"
},
"extra_fields": {
"provider": "anthropic",
"model_requested": "<string>",
"request_type": "<string>",
"error_type": "<string>",
"retry_after_ms": 150500
}
}{
"event_id": "<string>",
"type": "<string>",
"is_bifrost_error": true,
"status_code": 123,
"error": {
"type": "<string>",
"code": "<string>",
"message": "<string>",
"param": "<string>",
"event_id": "<string>"
},
"extra_fields": {
"provider": "anthropic",
"model_requested": "<string>",
"request_type": "<string>",
"error_type": "<string>",
"retry_after_ms": 150500
}
}{
"event_id": "<string>",
"type": "<string>",
"is_bifrost_error": true,
"status_code": 123,
"error": {
"type": "<string>",
"code": "<string>",
"message": "<string>",
"param": "<string>",
"event_id": "<string>"
},
"extra_fields": {
"provider": "anthropic",
"model_requested": "<string>",
"request_type": "<string>",
"error_type": "<string>",
"retry_after_ms": 150500
}
}Authorizations
Management API authentication for /api/* endpoints. Use the Authorization header
with Bearer <token>, where <token> is one of:
- a Bifrost management API key,
- a dashboard session token issued by
POST /api/session/login, - base64 of
<admin-username>:<admin-password>(legacy equivalent ofBasicAuth).
Virtual keys (sk-bf-*) and the x-api-key header are not accepted on management APIs -
the sole exception is GET /api/governance/virtual-keys/quota, which is virtual-key-only.
Authentication alone is not sufficient in Bifrost Enterprise: each operation page shows a
Required Permissions table (Resource:Operation, for example Dashboard:View) above
its Authorizations section, and the caller's RBAC role or management API key scopes must
include what it lists, otherwise the request is rejected with 403 Forbidden.
A local admin — authenticated with the admin password, or any caller on a deployment with dashboard auth disabled — bypasses these checks and can call every management endpoint.
OSS setup lock. On Bifrost OSS, while dashboard auth is not active (no admin account,
or auth disabled), every management endpoint except the public ones (/health,
/api/version, /api/session/is-auth-enabled, /api/session/login, ...) requires the
operator's setup token in the X-Bifrost-Setup-Token header, in place of Authorization.
The token is set with setup_token in config.json or the BIFROST_SETUP_TOKEN
environment variable. A missing header returns 401, a wrong token 403. The header
stops working once dashboard auth is enabled. The dashboard instead trades the token once
for an HttpOnly bifrost_setup_session cookie via POST /api/session/setup.
See Required permissions for how
permissions are derived and which endpoints are exempt.
Path Parameters
MCP client ID
Response
Reauthorization flow initiated against the newly registered client. Carries the same fields as reauthorize, plus registered_client_id and previous_client_id so the caller can confirm which client the consent it is about to run belongs to.
Response when initiating an OAuth flow
pending_oauth ID of the OAuth config created for this flow
ID of the flow row driving this consent. Returned by POST /api/mcp/client/{id}/reauthorize, whose OAuth config has been "authorized" since the client was first verified; pass it as the flow_id query parameter on status polls so they report this flow's own state rather than that stale bootstrap status. Create-time flows do not need it (their config starts "pending").
URL to redirect the user to for authorization
When the OAuth authorization request expires
The MCP client ID that initiated this OAuth flow
Relative URL to POST once the flow is authorized (/api/mcp/client/{oauth_config_id}/complete-oauth). Note the path parameter is the oauth_config_id, not the MCP client ID.
Relative URL to poll for the flow status (/api/oauth/config/{oauth_config_id}/status, with ?flow_id= appended for reauthorize flows). Wait for status "authorized" before calling complete_url.
Human-readable steps to complete the flow (authorize, poll, complete)
The OAuth client_id the provider issued for the replacement client, which is the one authorize_url runs consent against. Returned only by POST /api/mcp/client/{id}/reregister. This is the provider's OAuth client_id, not the MCP client ID in mcp_client_id.
The OAuth client_id that registered_client_id replaced. Returned only by POST /api/mcp/client/{id}/reregister. Equal to registered_client_id when the provider answered the registration with the client it already held, in which case nothing was replaced and no token was invalidated.
Was this page helpful?