> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getbifrost.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Update a key for a provider

> Updates an existing key. Send the full key object. Redacted values sent back
unchanged are automatically preserved (the server merges them with the stored
raw values).
Setting, changing, or removing any field that chooses the host Bifrost sends this
key's credentials to requires a genuinely authenticated admin session - it is refused
with 403 if dashboard authentication is disabled or unconfigured, even though other
management endpoints remain reachable in that state. Sending the stored values back
unchanged is allowed. ollama_key_config.url, sgl_key_config.url and
vllm_key_config.url also follow the provider base_url destination rule: private and
loopback hosts are accepted, link-local and unspecified addresses are refused with 400.
Key-level and per-alias regions must be vendor region identifiers (lowercase letters,
digits and hyphens, e.g. us-east-1); any other value is refused with 400.
Guarded fields: ollama_key_config.url, sgl_key_config.url, vllm_key_config.url,
azure_key_config.endpoint, databricks_key_config.workspace_url,
bedrock_key_config.endpoints.*, bedrock_mantle_key_config.endpoints.*,
sagemaker_key_config.endpoints.runtime, and
aliases.<name>.endpoint.


**Required Permissions**

| Permission | Granted via |
| - | - |
| `ModelProvider:Update` | RBAC role or API key scope |

[How permissions work](https://docs.getbifrost.ai/api/procuring-api-keys.md#required-permissions)


## OpenAPI

````yaml /openapi/openapi.json put /api/providers/{provider}/keys/{key_id}
openapi: 3.1.0
info:
  title: Bifrost API
  description: >
    Bifrost HTTP Transport API for AI model inference and gateway management.


    This API provides a unified interface for interacting with multiple AI
    providers

    including OpenAI, Anthropic, Bedrock, Gemini, and more through a single API,

    along with comprehensive management APIs for configuring and monitoring the
    gateway.


    ## API Structure


    ### Unified Inference API (`/v1/*`)

    The primary API using Bifrost's unified format. Model parameters use the
    format

    `provider/model` (e.g., `openai/gpt-4`, `anthropic/claude-3-opus`).


    ### Async Inference API (`/v1/async/*`)

    Submit inference requests for asynchronous execution. Returns a job ID
    immediately

    and allows polling for results. Supports all inference types except batches,
    files,

    and containers.


    ### Provider Integration APIs

    Native provider-format APIs for drop-in compatibility:

    - `/openai/*` - OpenAI-compatible API

    - `/anthropic/*` - Anthropic-compatible API

    - `/genai/*` - Google GenAI (Gemini) compatible API

    - `/bedrock/*` - AWS Bedrock compatible API

    - `/cohere/*` - Cohere compatible API


    ### Framework Integration APIs

    Multi-provider proxy endpoints for AI frameworks:

    - `/litellm/*` - LiteLLM proxy with all provider formats

    - `/langchain/*` - LangChain compatible endpoints

    - `/pydanticai/*` - PydanticAI compatible endpoints


    ### Management APIs (`/api/*`)

    APIs for managing and monitoring the Bifrost gateway:

    - `/api/config` - Configuration management

    - `/api/providers` - Provider and API key management

    - `/api/plugins` - Plugin management

    - `/api/governance/*` - Virtual keys, teams, customers, budgets, rate
    limits, routing rules, and pricing overrides

    - `/api/logs` - Log search and analytics

    - `/api/mcp/*` - MCP (Model Context Protocol) client management

    - `/api/session/*` - Authentication and session management

    - `/api/cache/*` - Cache management

    - `/health` - Health check endpoint


    ## Fallbacks

    Requests can include fallback models that will be tried if the primary model
    fails.
  version: 1.0.0
  contact:
    name: Contact Us
    url: https://getmaxim.ai/bifrost
  license:
    name: Apache 2.0
    url: https://opensource.org/licenses/Apache-2.0
servers:
  - url: '{baseUrl}'
    description: Your Bifrost instance
    variables:
      baseUrl:
        default: http://localhost:8080
        description: >-
          Base URL of your Bifrost instance (e.g. https://bifrost.mycompany.com,
          or https://mycompany.com/bifrost when served under server.base_path)
security:
  - BearerAuth: []
  - BasicAuth: []
  - ApiKeyAuth: []
tags:
  - name: Agent Gateway
    description: >-
      Agent registrations, A2A protocol calls, push callbacks, and operation
      history
  - name: Models
    description: Model listing and information
  - name: Chat Completions
    description: Chat-based text generation
  - name: Text Completions
    description: Text completion generation
  - name: Responses
    description: OpenAI Responses API compatible endpoints
  - name: OCR
    description: Optical character recognition for documents and images
  - name: Rerank
    description: Document reranking by relevance to a query
  - name: Decisions
    description: Structured decisions evaluated against annotated function-tool definitions
  - name: Embeddings
    description: Text embedding generation
  - name: Images
    description: Image generations, editing, and variations
  - name: Videos
    description: Video generation and management
  - name: Audio
    description: Speech synthesis and transcription
  - name: Count Tokens
    description: Token counting utilities
  - name: Batch
    description: Batch processing operations
  - name: Files
    description: File management operations
  - name: Containers
    description: Container management operations
  - name: Async Jobs
    description: Asynchronous job submission and retrieval endpoints
  - name: Realtime
    description: Realtime WebSocket and WebRTC endpoints
  - name: OpenAI Integration
    description: OpenAI-compatible API endpoints (/openai/*)
  - name: Azure Integration
    description: Azure OpenAI integration endpoints
  - name: Anthropic Integration
    description: Anthropic-compatible API endpoints (/anthropic/*)
  - name: GenAI Integration
    description: Google GenAI (Gemini) compatible API endpoints (/genai/*)
  - name: Bedrock Integration
    description: AWS Bedrock compatible API endpoints (/bedrock/*)
  - name: Cohere Integration
    description: Cohere compatible API endpoints (/cohere/*)
  - name: Typesafe Integration
    description: Typesafe compatible API endpoints (/typesafe/*)
  - name: LiteLLM Integration
    description: LiteLLM proxy endpoints with multi-provider support (/litellm/*)
  - name: LangChain Integration
    description: LangChain compatible endpoints with multi-provider support (/langchain/*)
  - name: PydanticAI Integration
    description: >-
      PydanticAI compatible endpoints with multi-provider support
      (/pydanticai/*)
  - name: Health
    description: Health check endpoints
  - name: Configuration
    description: Configuration management endpoints
  - name: Session
    description: Session and authentication endpoints
  - name: Providers
    description: Provider management endpoints
  - name: Plugins
    description: Plugin management endpoints
  - name: MCP
    description: Model Context Protocol endpoints
  - name: Governance
    description: Virtual keys, teams, and customers management
  - name: Routing
    description: Routing rules and complexity analyzer configuration
  - name: Logging
    description: Log search and management endpoints
  - name: Cache
    description: Cache management endpoints
  - name: Vault
    description: Vault secret management endpoints
  - name: Skills
    description: Skills Repository management, marketplace, and download endpoints
  - name: Audit Logs
    description: >-
      CADF-compliant audit log search, export, and signature verification
      endpoints
  - name: Webhooks
    description: Webhook endpoint management and signed async-job delivery history
  - name: Notifications
    description: >-
      Role-targeted dashboard notifications, delivered over the dashboard
      WebSocket
  - name: News Feeds
    description: >-
      RSS and Atom news sources shown in the News tab of the dashboard
      notification tray
  - name: Background Jobs
    description: >-
      Status, progress and cancellation of durable background jobs (cost
      recalculation, Warp log indexing, and others)
  - name: Warp
    description: >-
      Configuration for Warp, the dashboard agent that answers questions about
      the deployment's own telemetry
  - name: Relays
    description: >-
      Relays to non-LLM HTTP APIs - endpoint management, usage preview, Relay
      Logs and the /relay data plane
paths:
  /api/providers/{provider}/keys/{key_id}:
    put:
      tags:
        - Providers
      summary: Update a key for a provider
      description: >
        Updates an existing key. Send the full key object. Redacted values sent
        back

        unchanged are automatically preserved (the server merges them with the
        stored

        raw values).

        Setting, changing, or removing any field that chooses the host Bifrost
        sends this

        key's credentials to requires a genuinely authenticated admin session -
        it is refused

        with 403 if dashboard authentication is disabled or unconfigured, even
        though other

        management endpoints remain reachable in that state. Sending the stored
        values back

        unchanged is allowed. ollama_key_config.url, sgl_key_config.url and

        vllm_key_config.url also follow the provider base_url destination rule:
        private and

        loopback hosts are accepted, link-local and unspecified addresses are
        refused with 400.

        Key-level and per-alias regions must be vendor region identifiers
        (lowercase letters,

        digits and hyphens, e.g. us-east-1); any other value is refused with
        400.

        Guarded fields: ollama_key_config.url, sgl_key_config.url,
        vllm_key_config.url,

        azure_key_config.endpoint, databricks_key_config.workspace_url,

        bedrock_key_config.endpoints.*, bedrock_mantle_key_config.endpoints.*,

        sagemaker_key_config.endpoints.runtime, and

        aliases.<name>.endpoint.
      operationId: updateProviderKey
      parameters:
        - name: provider
          in: path
          required: true
          description: Provider name
          schema:
            type: string
        - name: key_id
          in: path
          required: true
          description: Key ID
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Key'
      responses:
        '200':
          description: Key updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Key'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BifrostError'
        '403':
          description: >-
            A key endpoint field was set, changed, or removed and dashboard
            authentication is disabled or unconfigured (the request was not
            genuinely authenticated)
        '404':
          description: Provider or key not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BifrostError'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BifrostError'
      security:
        - ManagementBearerAuth: []
        - BasicAuth: []
components:
  schemas:
    Key:
      type: object
      description: API key configuration
      properties:
        id:
          type: string
          description: Unique identifier for the key
        name:
          type: string
          description: Name of the key
        value:
          description: API key value (redacted in responses)
          oneOf:
            - type: string
              description: >-
                Bare input form — plain text, `env.VAR_NAME`, or
                `vault.path/to/secret`
            - type: object
              description: Resolved form, as returned by GET responses
              properties:
                value:
                  type: string
                  description: Resolved value (redacted in GET responses for secret fields)
                ref:
                  type: string
                  description: >-
                    Source reference (`env.VAR_NAME` or `vault.path`); empty for
                    plain-text values
                type:
                  type: string
                  enum:
                    - plain_text
                    - env
                    - vault
                  description: Source type of the value
        models:
          type: array
          items:
            type: string
          description: >-
            List of models this key can access (whitelist). `["*"]` allows every
            model. An entry starting with `regex:` is an RE2 pattern matched
            case-insensitively against the whole model name; an empty pattern,
            `regex:*`, or a pattern that does not compile is rejected with 400.
            `blacklisted_models` wins over this list.
        blacklisted_models:
          type: array
          items:
            type: string
          description: >-
            List of models this key cannot access (blacklist), which wins over
            `models`. `["*"]` blocks every model. An entry starting with
            `regex:` is an RE2 pattern matched case-insensitively against the
            whole model name; an empty pattern, `regex:*`, or a pattern that
            does not compile is rejected with 400.
        weight:
          type: number
          minimum: 0
          description: >-
            Weight for load balancing. A negative weight is rejected with 400. A
            key with weight 0 is picked only when no other eligible key has a
            positive weight; when every weight is 0, keys are picked uniformly.
        aliases:
          type: object
          propertyNames:
            minLength: 1
          additionalProperties:
            type: string
            minLength: 1
          description: >-
            Model alias mappings - maps a user-facing model name to a
            provider-specific identifier (deployment name, inference profile ID,
            fine-tuned model ID, etc.)
        azure_key_config:
          type: object
          description: Azure-specific key configuration
          properties:
            endpoint:
              description: >
                A secret-capable value. Serialized as an object with the
                resolved `value` plus

                reference metadata; on input, a bare string is also accepted —
                plain text,

                `env.VAR_NAME`, or `vault.path/to/secret` (references resolve at
                runtime and

                only the reference is persisted).
              oneOf:
                - type: string
                  description: >-
                    Bare input form — plain text, `env.VAR_NAME`, or
                    `vault.path/to/secret`
                - type: object
                  description: Resolved form, as returned by GET responses
                  properties:
                    value:
                      type: string
                      description: >-
                        Resolved value (redacted in GET responses for secret
                        fields)
                    ref:
                      type: string
                      description: >-
                        Source reference (`env.VAR_NAME` or `vault.path`); empty
                        for plain-text values
                    type:
                      type: string
                      enum:
                        - plain_text
                        - env
                        - vault
                      description: Source type of the value
            api_version:
              description: >
                A secret-capable value. Serialized as an object with the
                resolved `value` plus

                reference metadata; on input, a bare string is also accepted —
                plain text,

                `env.VAR_NAME`, or `vault.path/to/secret` (references resolve at
                runtime and

                only the reference is persisted).
              oneOf:
                - type: string
                  description: >-
                    Bare input form — plain text, `env.VAR_NAME`, or
                    `vault.path/to/secret`
                - type: object
                  description: Resolved form, as returned by GET responses
                  properties:
                    value:
                      type: string
                      description: >-
                        Resolved value (redacted in GET responses for secret
                        fields)
                    ref:
                      type: string
                      description: >-
                        Source reference (`env.VAR_NAME` or `vault.path`); empty
                        for plain-text values
                    type:
                      type: string
                      enum:
                        - plain_text
                        - env
                        - vault
                      description: Source type of the value
            client_id:
              description: >
                A secret-capable value. Serialized as an object with the
                resolved `value` plus

                reference metadata; on input, a bare string is also accepted —
                plain text,

                `env.VAR_NAME`, or `vault.path/to/secret` (references resolve at
                runtime and

                only the reference is persisted).
              oneOf:
                - type: string
                  description: >-
                    Bare input form — plain text, `env.VAR_NAME`, or
                    `vault.path/to/secret`
                - type: object
                  description: Resolved form, as returned by GET responses
                  properties:
                    value:
                      type: string
                      description: >-
                        Resolved value (redacted in GET responses for secret
                        fields)
                    ref:
                      type: string
                      description: >-
                        Source reference (`env.VAR_NAME` or `vault.path`); empty
                        for plain-text values
                    type:
                      type: string
                      enum:
                        - plain_text
                        - env
                        - vault
                      description: Source type of the value
            client_secret:
              description: >
                A secret-capable value. Serialized as an object with the
                resolved `value` plus

                reference metadata; on input, a bare string is also accepted —
                plain text,

                `env.VAR_NAME`, or `vault.path/to/secret` (references resolve at
                runtime and

                only the reference is persisted).
              oneOf:
                - type: string
                  description: >-
                    Bare input form — plain text, `env.VAR_NAME`, or
                    `vault.path/to/secret`
                - type: object
                  description: Resolved form, as returned by GET responses
                  properties:
                    value:
                      type: string
                      description: >-
                        Resolved value (redacted in GET responses for secret
                        fields)
                    ref:
                      type: string
                      description: >-
                        Source reference (`env.VAR_NAME` or `vault.path`); empty
                        for plain-text values
                    type:
                      type: string
                      enum:
                        - plain_text
                        - env
                        - vault
                      description: Source type of the value
            tenant_id:
              description: >
                A secret-capable value. Serialized as an object with the
                resolved `value` plus

                reference metadata; on input, a bare string is also accepted —
                plain text,

                `env.VAR_NAME`, or `vault.path/to/secret` (references resolve at
                runtime and

                only the reference is persisted).
              oneOf:
                - type: string
                  description: >-
                    Bare input form — plain text, `env.VAR_NAME`, or
                    `vault.path/to/secret`
                - type: object
                  description: Resolved form, as returned by GET responses
                  properties:
                    value:
                      type: string
                      description: >-
                        Resolved value (redacted in GET responses for secret
                        fields)
                    ref:
                      type: string
                      description: >-
                        Source reference (`env.VAR_NAME` or `vault.path`); empty
                        for plain-text values
                    type:
                      type: string
                      enum:
                        - plain_text
                        - env
                        - vault
                      description: Source type of the value
            scopes:
              type: array
              items:
                type: string
              description: List of scopes to use for authentication
            use_speech_endpoints:
              type: boolean
              default: false
              description: >-
                Send speech and transcription requests to Azure AI Speech (SSML
                text to speech, fast transcription) instead of Azure OpenAI. An
                alias can override it with its own use_speech_endpoints.
            use_voice_live_endpoints:
              type: boolean
              default: false
              description: >-
                Send realtime WebSocket sessions to Azure Voice Live
                (/voice-live/realtime) instead of Azure OpenAI. The WebRTC and
                client secret routes reject it. An alias can override it with
                its own use_voice_live_endpoints.
        vertex_key_config:
          type: object
          description: Vertex-specific key configuration
          properties:
            project_id:
              description: >
                A secret-capable value. Serialized as an object with the
                resolved `value` plus

                reference metadata; on input, a bare string is also accepted —
                plain text,

                `env.VAR_NAME`, or `vault.path/to/secret` (references resolve at
                runtime and

                only the reference is persisted).
              oneOf:
                - type: string
                  description: >-
                    Bare input form — plain text, `env.VAR_NAME`, or
                    `vault.path/to/secret`
                - type: object
                  description: Resolved form, as returned by GET responses
                  properties:
                    value:
                      type: string
                      description: >-
                        Resolved value (redacted in GET responses for secret
                        fields)
                    ref:
                      type: string
                      description: >-
                        Source reference (`env.VAR_NAME` or `vault.path`); empty
                        for plain-text values
                    type:
                      type: string
                      enum:
                        - plain_text
                        - env
                        - vault
                      description: Source type of the value
            project_number:
              description: >
                A secret-capable value. Serialized as an object with the
                resolved `value` plus

                reference metadata; on input, a bare string is also accepted —
                plain text,

                `env.VAR_NAME`, or `vault.path/to/secret` (references resolve at
                runtime and

                only the reference is persisted).
              oneOf:
                - type: string
                  description: >-
                    Bare input form — plain text, `env.VAR_NAME`, or
                    `vault.path/to/secret`
                - type: object
                  description: Resolved form, as returned by GET responses
                  properties:
                    value:
                      type: string
                      description: >-
                        Resolved value (redacted in GET responses for secret
                        fields)
                    ref:
                      type: string
                      description: >-
                        Source reference (`env.VAR_NAME` or `vault.path`); empty
                        for plain-text values
                    type:
                      type: string
                      enum:
                        - plain_text
                        - env
                        - vault
                      description: Source type of the value
            region:
              description: >
                A secret-capable value. Serialized as an object with the
                resolved `value` plus

                reference metadata; on input, a bare string is also accepted —
                plain text,

                `env.VAR_NAME`, or `vault.path/to/secret` (references resolve at
                runtime and

                only the reference is persisted).
              oneOf:
                - type: string
                  description: >-
                    Bare input form — plain text, `env.VAR_NAME`, or
                    `vault.path/to/secret`
                - type: object
                  description: Resolved form, as returned by GET responses
                  properties:
                    value:
                      type: string
                      description: >-
                        Resolved value (redacted in GET responses for secret
                        fields)
                    ref:
                      type: string
                      description: >-
                        Source reference (`env.VAR_NAME` or `vault.path`); empty
                        for plain-text values
                    type:
                      type: string
                      enum:
                        - plain_text
                        - env
                        - vault
                      description: Source type of the value
            auth_credentials:
              description: >
                A secret-capable value. Serialized as an object with the
                resolved `value` plus

                reference metadata; on input, a bare string is also accepted —
                plain text,

                `env.VAR_NAME`, or `vault.path/to/secret` (references resolve at
                runtime and

                only the reference is persisted).
              oneOf:
                - type: string
                  description: >-
                    Bare input form — plain text, `env.VAR_NAME`, or
                    `vault.path/to/secret`
                - type: object
                  description: Resolved form, as returned by GET responses
                  properties:
                    value:
                      type: string
                      description: >-
                        Resolved value (redacted in GET responses for secret
                        fields)
                    ref:
                      type: string
                      description: >-
                        Source reference (`env.VAR_NAME` or `vault.path`); empty
                        for plain-text values
                    type:
                      type: string
                      enum:
                        - plain_text
                        - env
                        - vault
                      description: Source type of the value
            force_single_region:
              type: boolean
              default: false
              description: >-
                When true, always call the configured region and skip automatic
                promotion of multi-region-only models to a multi-region
                endpoint.
            use_session_routing:
              type: boolean
              default: false
              description: >-
                Send each request's prompt_cache_key to Gemini models as
                session_id. Vertex routes requests with the same session ID to
                one replica, so they reuse its implicit cache. Enable only if
                Google has turned on session routing for this key's project.
            aws_workload_identity:
              type: object
              description: >-
                GCP Workload Identity Federation from the workload's AWS
                identity (EKS IRSA / Pod Identity, ECS task role, EC2 instance
                profile, AWS_* env vars). Takes precedence over
                auth_credentials; the two must not be combined. aws_role_arn is
                redacted in GET responses; the other fields are identifiers and
                are returned in clear.
              properties:
                audience:
                  description: >
                    A secret-capable value. Serialized as an object with the
                    resolved `value` plus

                    reference metadata; on input, a bare string is also accepted
                    — plain text,

                    `env.VAR_NAME`, or `vault.path/to/secret` (references
                    resolve at runtime and

                    only the reference is persisted).
                  oneOf:
                    - type: string
                      description: >-
                        Bare input form — plain text, `env.VAR_NAME`, or
                        `vault.path/to/secret`
                    - type: object
                      description: Resolved form, as returned by GET responses
                      properties:
                        value:
                          type: string
                          description: >-
                            Resolved value (redacted in GET responses for secret
                            fields)
                        ref:
                          type: string
                          description: >-
                            Source reference (`env.VAR_NAME` or `vault.path`);
                            empty for plain-text values
                        type:
                          type: string
                          enum:
                            - plain_text
                            - env
                            - vault
                          description: Source type of the value
                service_account_email:
                  description: >
                    A secret-capable value. Serialized as an object with the
                    resolved `value` plus

                    reference metadata; on input, a bare string is also accepted
                    — plain text,

                    `env.VAR_NAME`, or `vault.path/to/secret` (references
                    resolve at runtime and

                    only the reference is persisted).
                  oneOf:
                    - type: string
                      description: >-
                        Bare input form — plain text, `env.VAR_NAME`, or
                        `vault.path/to/secret`
                    - type: object
                      description: Resolved form, as returned by GET responses
                      properties:
                        value:
                          type: string
                          description: >-
                            Resolved value (redacted in GET responses for secret
                            fields)
                        ref:
                          type: string
                          description: >-
                            Source reference (`env.VAR_NAME` or `vault.path`);
                            empty for plain-text values
                        type:
                          type: string
                          enum:
                            - plain_text
                            - env
                            - vault
                          description: Source type of the value
                token_lifetime_seconds:
                  type: integer
                  minimum: 600
                  maximum: 43200
                  description: >-
                    Lifetime of the impersonated service-account token in
                    seconds; only used with service_account_email. Default 3600.
                    Lifetimes above 3600 require the target service account to
                    be allowed by the organization policy constraint
                    constraints/iam.allowServiceAccountCredentialLifetimeExtension;
                    otherwise token generation fails.
                aws_region:
                  description: >
                    A secret-capable value. Serialized as an object with the
                    resolved `value` plus

                    reference metadata; on input, a bare string is also accepted
                    — plain text,

                    `env.VAR_NAME`, or `vault.path/to/secret` (references
                    resolve at runtime and

                    only the reference is persisted).
                  oneOf:
                    - type: string
                      description: >-
                        Bare input form — plain text, `env.VAR_NAME`, or
                        `vault.path/to/secret`
                    - type: object
                      description: Resolved form, as returned by GET responses
                      properties:
                        value:
                          type: string
                          description: >-
                            Resolved value (redacted in GET responses for secret
                            fields)
                        ref:
                          type: string
                          description: >-
                            Source reference (`env.VAR_NAME` or `vault.path`);
                            empty for plain-text values
                        type:
                          type: string
                          enum:
                            - plain_text
                            - env
                            - vault
                          description: Source type of the value
                aws_role_arn:
                  description: >
                    A secret-capable value. Serialized as an object with the
                    resolved `value` plus

                    reference metadata; on input, a bare string is also accepted
                    — plain text,

                    `env.VAR_NAME`, or `vault.path/to/secret` (references
                    resolve at runtime and

                    only the reference is persisted).
                  oneOf:
                    - type: string
                      description: >-
                        Bare input form — plain text, `env.VAR_NAME`, or
                        `vault.path/to/secret`
                    - type: object
                      description: Resolved form, as returned by GET responses
                      properties:
                        value:
                          type: string
                          description: >-
                            Resolved value (redacted in GET responses for secret
                            fields)
                        ref:
                          type: string
                          description: >-
                            Source reference (`env.VAR_NAME` or `vault.path`);
                            empty for plain-text values
                        type:
                          type: string
                          enum:
                            - plain_text
                            - env
                            - vault
                          description: Source type of the value
              required:
                - audience
              additionalProperties: false
          if:
            required:
              - aws_workload_identity
          then:
            properties:
              auth_credentials:
                anyOf:
                  - type: string
                    maxLength: 0
                  - type: object
                    properties:
                      value:
                        type: string
                        maxLength: 0
                      ref:
                        type: string
                        maxLength: 0
        bedrock_key_config:
          type: object
          description: AWS Bedrock-specific key configuration
          properties:
            access_key:
              description: >
                A secret-capable value. Serialized as an object with the
                resolved `value` plus

                reference metadata; on input, a bare string is also accepted —
                plain text,

                `env.VAR_NAME`, or `vault.path/to/secret` (references resolve at
                runtime and

                only the reference is persisted).
              oneOf:
                - type: string
                  description: >-
                    Bare input form — plain text, `env.VAR_NAME`, or
                    `vault.path/to/secret`
                - type: object
                  description: Resolved form, as returned by GET responses
                  properties:
                    value:
                      type: string
                      description: >-
                        Resolved value (redacted in GET responses for secret
                        fields)
                    ref:
                      type: string
                      description: >-
                        Source reference (`env.VAR_NAME` or `vault.path`); empty
                        for plain-text values
                    type:
                      type: string
                      enum:
                        - plain_text
                        - env
                        - vault
                      description: Source type of the value
            secret_key:
              description: >
                A secret-capable value. Serialized as an object with the
                resolved `value` plus

                reference metadata; on input, a bare string is also accepted —
                plain text,

                `env.VAR_NAME`, or `vault.path/to/secret` (references resolve at
                runtime and

                only the reference is persisted).
              oneOf:
                - type: string
                  description: >-
                    Bare input form — plain text, `env.VAR_NAME`, or
                    `vault.path/to/secret`
                - type: object
                  description: Resolved form, as returned by GET responses
                  properties:
                    value:
                      type: string
                      description: >-
                        Resolved value (redacted in GET responses for secret
                        fields)
                    ref:
                      type: string
                      description: >-
                        Source reference (`env.VAR_NAME` or `vault.path`); empty
                        for plain-text values
                    type:
                      type: string
                      enum:
                        - plain_text
                        - env
                        - vault
                      description: Source type of the value
            session_token:
              description: >
                A secret-capable value. Serialized as an object with the
                resolved `value` plus

                reference metadata; on input, a bare string is also accepted —
                plain text,

                `env.VAR_NAME`, or `vault.path/to/secret` (references resolve at
                runtime and

                only the reference is persisted).
              oneOf:
                - type: string
                  description: >-
                    Bare input form — plain text, `env.VAR_NAME`, or
                    `vault.path/to/secret`
                - type: object
                  description: Resolved form, as returned by GET responses
                  properties:
                    value:
                      type: string
                      description: >-
                        Resolved value (redacted in GET responses for secret
                        fields)
                    ref:
                      type: string
                      description: >-
                        Source reference (`env.VAR_NAME` or `vault.path`); empty
                        for plain-text values
                    type:
                      type: string
                      enum:
                        - plain_text
                        - env
                        - vault
                      description: Source type of the value
            region:
              description: >
                A secret-capable value. Serialized as an object with the
                resolved `value` plus

                reference metadata; on input, a bare string is also accepted —
                plain text,

                `env.VAR_NAME`, or `vault.path/to/secret` (references resolve at
                runtime and

                only the reference is persisted).
              oneOf:
                - type: string
                  description: >-
                    Bare input form — plain text, `env.VAR_NAME`, or
                    `vault.path/to/secret`
                - type: object
                  description: Resolved form, as returned by GET responses
                  properties:
                    value:
                      type: string
                      description: >-
                        Resolved value (redacted in GET responses for secret
                        fields)
                    ref:
                      type: string
                      description: >-
                        Source reference (`env.VAR_NAME` or `vault.path`); empty
                        for plain-text values
                    type:
                      type: string
                      enum:
                        - plain_text
                        - env
                        - vault
                      description: Source type of the value
            arn:
              description: >
                A secret-capable value. Serialized as an object with the
                resolved `value` plus

                reference metadata; on input, a bare string is also accepted —
                plain text,

                `env.VAR_NAME`, or `vault.path/to/secret` (references resolve at
                runtime and

                only the reference is persisted).
              oneOf:
                - type: string
                  description: >-
                    Bare input form — plain text, `env.VAR_NAME`, or
                    `vault.path/to/secret`
                - type: object
                  description: Resolved form, as returned by GET responses
                  properties:
                    value:
                      type: string
                      description: >-
                        Resolved value (redacted in GET responses for secret
                        fields)
                    ref:
                      type: string
                      description: >-
                        Source reference (`env.VAR_NAME` or `vault.path`); empty
                        for plain-text values
                    type:
                      type: string
                      enum:
                        - plain_text
                        - env
                        - vault
                      description: Source type of the value
            batch_s3_config:
              type: object
              properties:
                buckets:
                  type: array
                  items:
                    type: object
                    properties:
                      bucket_name:
                        type: string
                      prefix:
                        type: string
                      is_default:
                        type: boolean
        sagemaker_key_config:
          type: object
          description: >-
            AWS SageMaker real-time endpoint key configuration. A pre-minted
            token in Key.value takes precedence and is sent as is; otherwise
            Bifrost mints the SageMaker bearer token from these AWS credentials
            (leave access_key and secret_key empty to use the default AWS
            credential chain). Passthrough signs requests with AWS credentials
            and rejects keys that set Key.value.
          properties:
            access_key:
              description: >
                A secret-capable value. Serialized as an object with the
                resolved `value` plus

                reference metadata; on input, a bare string is also accepted —
                plain text,

                `env.VAR_NAME`, or `vault.path/to/secret` (references resolve at
                runtime and

                only the reference is persisted).
              oneOf:
                - type: string
                  description: >-
                    Bare input form — plain text, `env.VAR_NAME`, or
                    `vault.path/to/secret`
                - type: object
                  description: Resolved form, as returned by GET responses
                  properties:
                    value:
                      type: string
                      description: >-
                        Resolved value (redacted in GET responses for secret
                        fields)
                    ref:
                      type: string
                      description: >-
                        Source reference (`env.VAR_NAME` or `vault.path`); empty
                        for plain-text values
                    type:
                      type: string
                      enum:
                        - plain_text
                        - env
                        - vault
                      description: Source type of the value
            secret_key:
              description: >
                A secret-capable value. Serialized as an object with the
                resolved `value` plus

                reference metadata; on input, a bare string is also accepted —
                plain text,

                `env.VAR_NAME`, or `vault.path/to/secret` (references resolve at
                runtime and

                only the reference is persisted).
              oneOf:
                - type: string
                  description: >-
                    Bare input form — plain text, `env.VAR_NAME`, or
                    `vault.path/to/secret`
                - type: object
                  description: Resolved form, as returned by GET responses
                  properties:
                    value:
                      type: string
                      description: >-
                        Resolved value (redacted in GET responses for secret
                        fields)
                    ref:
                      type: string
                      description: >-
                        Source reference (`env.VAR_NAME` or `vault.path`); empty
                        for plain-text values
                    type:
                      type: string
                      enum:
                        - plain_text
                        - env
                        - vault
                      description: Source type of the value
            session_token:
              description: >
                A secret-capable value. Serialized as an object with the
                resolved `value` plus

                reference metadata; on input, a bare string is also accepted —
                plain text,

                `env.VAR_NAME`, or `vault.path/to/secret` (references resolve at
                runtime and

                only the reference is persisted).
              oneOf:
                - type: string
                  description: >-
                    Bare input form — plain text, `env.VAR_NAME`, or
                    `vault.path/to/secret`
                - type: object
                  description: Resolved form, as returned by GET responses
                  properties:
                    value:
                      type: string
                      description: >-
                        Resolved value (redacted in GET responses for secret
                        fields)
                    ref:
                      type: string
                      description: >-
                        Source reference (`env.VAR_NAME` or `vault.path`); empty
                        for plain-text values
                    type:
                      type: string
                      enum:
                        - plain_text
                        - env
                        - vault
                      description: Source type of the value
            region:
              description: >
                A secret-capable value. Serialized as an object with the
                resolved `value` plus

                reference metadata; on input, a bare string is also accepted —
                plain text,

                `env.VAR_NAME`, or `vault.path/to/secret` (references resolve at
                runtime and

                only the reference is persisted).
              oneOf:
                - type: string
                  description: >-
                    Bare input form — plain text, `env.VAR_NAME`, or
                    `vault.path/to/secret`
                - type: object
                  description: Resolved form, as returned by GET responses
                  properties:
                    value:
                      type: string
                      description: >-
                        Resolved value (redacted in GET responses for secret
                        fields)
                    ref:
                      type: string
                      description: >-
                        Source reference (`env.VAR_NAME` or `vault.path`); empty
                        for plain-text values
                    type:
                      type: string
                      enum:
                        - plain_text
                        - env
                        - vault
                      description: Source type of the value
            role_arn:
              description: >
                A secret-capable value. Serialized as an object with the
                resolved `value` plus

                reference metadata; on input, a bare string is also accepted —
                plain text,

                `env.VAR_NAME`, or `vault.path/to/secret` (references resolve at
                runtime and

                only the reference is persisted).
              oneOf:
                - type: string
                  description: >-
                    Bare input form — plain text, `env.VAR_NAME`, or
                    `vault.path/to/secret`
                - type: object
                  description: Resolved form, as returned by GET responses
                  properties:
                    value:
                      type: string
                      description: >-
                        Resolved value (redacted in GET responses for secret
                        fields)
                    ref:
                      type: string
                      description: >-
                        Source reference (`env.VAR_NAME` or `vault.path`); empty
                        for plain-text values
                    type:
                      type: string
                      enum:
                        - plain_text
                        - env
                        - vault
                      description: Source type of the value
            external_id:
              description: >
                A secret-capable value. Serialized as an object with the
                resolved `value` plus

                reference metadata; on input, a bare string is also accepted —
                plain text,

                `env.VAR_NAME`, or `vault.path/to/secret` (references resolve at
                runtime and

                only the reference is persisted).
              oneOf:
                - type: string
                  description: >-
                    Bare input form — plain text, `env.VAR_NAME`, or
                    `vault.path/to/secret`
                - type: object
                  description: Resolved form, as returned by GET responses
                  properties:
                    value:
                      type: string
                      description: >-
                        Resolved value (redacted in GET responses for secret
                        fields)
                    ref:
                      type: string
                      description: >-
                        Source reference (`env.VAR_NAME` or `vault.path`); empty
                        for plain-text values
                    type:
                      type: string
                      enum:
                        - plain_text
                        - env
                        - vault
                      description: Source type of the value
            session_name:
              description: >
                A secret-capable value. Serialized as an object with the
                resolved `value` plus

                reference metadata; on input, a bare string is also accepted —
                plain text,

                `env.VAR_NAME`, or `vault.path/to/secret` (references resolve at
                runtime and

                only the reference is persisted).
              oneOf:
                - type: string
                  description: >-
                    Bare input form — plain text, `env.VAR_NAME`, or
                    `vault.path/to/secret`
                - type: object
                  description: Resolved form, as returned by GET responses
                  properties:
                    value:
                      type: string
                      description: >-
                        Resolved value (redacted in GET responses for secret
                        fields)
                    ref:
                      type: string
                      description: >-
                        Source reference (`env.VAR_NAME` or `vault.path`); empty
                        for plain-text values
                    type:
                      type: string
                      enum:
                        - plain_text
                        - env
                        - vault
                      description: Source type of the value
            endpoints:
              type: object
              description: Runtime host override (VPC endpoint, FIPS or dual-stack host)
              properties:
                runtime:
                  description: >
                    A secret-capable value. Serialized as an object with the
                    resolved `value` plus

                    reference metadata; on input, a bare string is also accepted
                    — plain text,

                    `env.VAR_NAME`, or `vault.path/to/secret` (references
                    resolve at runtime and

                    only the reference is persisted).
                  oneOf:
                    - type: string
                      description: >-
                        Bare input form — plain text, `env.VAR_NAME`, or
                        `vault.path/to/secret`
                    - type: object
                      description: Resolved form, as returned by GET responses
                      properties:
                        value:
                          type: string
                          description: >-
                            Resolved value (redacted in GET responses for secret
                            fields)
                        ref:
                          type: string
                          description: >-
                            Source reference (`env.VAR_NAME` or `vault.path`);
                            empty for plain-text values
                        type:
                          type: string
                          enum:
                            - plain_text
                            - env
                            - vault
                          description: Source type of the value
              additionalProperties: false
          required:
            - region
          additionalProperties: false
        vllm_key_config:
          type: object
          description: VLLM-specific key configuration
          properties:
            url:
              description: >
                A secret-capable value. Serialized as an object with the
                resolved `value` plus

                reference metadata; on input, a bare string is also accepted —
                plain text,

                `env.VAR_NAME`, or `vault.path/to/secret` (references resolve at
                runtime and

                only the reference is persisted).
              oneOf:
                - type: string
                  description: >-
                    Bare input form — plain text, `env.VAR_NAME`, or
                    `vault.path/to/secret`
                - type: object
                  description: Resolved form, as returned by GET responses
                  properties:
                    value:
                      type: string
                      description: >-
                        Resolved value (redacted in GET responses for secret
                        fields)
                    ref:
                      type: string
                      description: >-
                        Source reference (`env.VAR_NAME` or `vault.path`); empty
                        for plain-text values
                    type:
                      type: string
                      enum:
                        - plain_text
                        - env
                        - vault
                      description: Source type of the value
            model_name:
              type: string
          required:
            - url
        ollama_key_config:
          type: object
          description: Ollama-specific key configuration
          properties:
            url:
              description: >
                A secret-capable value. Serialized as an object with the
                resolved `value` plus

                reference metadata; on input, a bare string is also accepted —
                plain text,

                `env.VAR_NAME`, or `vault.path/to/secret` (references resolve at
                runtime and

                only the reference is persisted).
              oneOf:
                - type: string
                  description: >-
                    Bare input form — plain text, `env.VAR_NAME`, or
                    `vault.path/to/secret`
                - type: object
                  description: Resolved form, as returned by GET responses
                  properties:
                    value:
                      type: string
                      description: >-
                        Resolved value (redacted in GET responses for secret
                        fields)
                    ref:
                      type: string
                      description: >-
                        Source reference (`env.VAR_NAME` or `vault.path`); empty
                        for plain-text values
                    type:
                      type: string
                      enum:
                        - plain_text
                        - env
                        - vault
                      description: Source type of the value
          required:
            - url
        sgl_key_config:
          type: object
          description: SGLang-specific key configuration
          properties:
            url:
              description: >
                A secret-capable value. Serialized as an object with the
                resolved `value` plus

                reference metadata; on input, a bare string is also accepted —
                plain text,

                `env.VAR_NAME`, or `vault.path/to/secret` (references resolve at
                runtime and

                only the reference is persisted).
              oneOf:
                - type: string
                  description: >-
                    Bare input form — plain text, `env.VAR_NAME`, or
                    `vault.path/to/secret`
                - type: object
                  description: Resolved form, as returned by GET responses
                  properties:
                    value:
                      type: string
                      description: >-
                        Resolved value (redacted in GET responses for secret
                        fields)
                    ref:
                      type: string
                      description: >-
                        Source reference (`env.VAR_NAME` or `vault.path`); empty
                        for plain-text values
                    type:
                      type: string
                      enum:
                        - plain_text
                        - env
                        - vault
                      description: Source type of the value
          required:
            - url
        cloudflare_key_config:
          type: object
          description: Cloudflare Workers AI-specific key configuration
          properties:
            account_id:
              description: >
                A secret-capable value. Serialized as an object with the
                resolved `value` plus

                reference metadata; on input, a bare string is also accepted —
                plain text,

                `env.VAR_NAME`, or `vault.path/to/secret` (references resolve at
                runtime and

                only the reference is persisted).
              oneOf:
                - type: string
                  description: >-
                    Bare input form — plain text, `env.VAR_NAME`, or
                    `vault.path/to/secret`
                - type: object
                  description: Resolved form, as returned by GET responses
                  properties:
                    value:
                      type: string
                      description: >-
                        Resolved value (redacted in GET responses for secret
                        fields)
                    ref:
                      type: string
                      description: >-
                        Source reference (`env.VAR_NAME` or `vault.path`); empty
                        for plain-text values
                    type:
                      type: string
                      enum:
                        - plain_text
                        - env
                        - vault
                      description: Source type of the value
          required:
            - account_id
        replicate_key_config:
          type: object
          description: Replicate-specific key configuration
          properties:
            use_deployments_endpoint:
              type: boolean
              description: >-
                Whether to use the deployments endpoint instead of the models
                endpoint
        oauth_key_config:
          type: object
          description: >-
            OAuth-minted bearer for OpenAI-compatible providers (including
            custom providers on the openai base). Set this and leave value
            empty; Bifrost mints, caches and refreshes the access token. A
            non-empty value always wins. Secrets are redacted in responses.
          required:
            - grant_type
            - token_url
          properties:
            grant_type:
              type: string
              enum:
                - client_credentials
                - jwt_bearer
              description: >-
                client_credentials (RFC 6749 §4.4) or jwt_bearer (RFC 7523,
                Bifrost signs an assertion with private_key)
            token_url:
              description: >-
                Token endpoint, absolute https URL (plain http is accepted for
                loopback hosts only). Must not carry userinfo, a query or a
                fragment; send extra parameters through extra_params
              oneOf:
                - type: string
                  description: >-
                    Bare input form — plain text, `env.VAR_NAME`, or
                    `vault.path/to/secret`
                - type: object
                  description: Resolved form, as returned by GET responses
                  properties:
                    value:
                      type: string
                      description: >-
                        Resolved value (redacted in GET responses for secret
                        fields)
                    ref:
                      type: string
                      description: >-
                        Source reference (`env.VAR_NAME` or `vault.path`); empty
                        for plain-text values
                    type:
                      type: string
                      enum:
                        - plain_text
                        - env
                        - vault
                      description: Source type of the value
            client_id:
              description: client_credentials client ID (redacted in responses)
              oneOf:
                - type: string
                  description: >-
                    Bare input form — plain text, `env.VAR_NAME`, or
                    `vault.path/to/secret`
                - type: object
                  description: Resolved form, as returned by GET responses
                  properties:
                    value:
                      type: string
                      description: >-
                        Resolved value (redacted in GET responses for secret
                        fields)
                    ref:
                      type: string
                      description: >-
                        Source reference (`env.VAR_NAME` or `vault.path`); empty
                        for plain-text values
                    type:
                      type: string
                      enum:
                        - plain_text
                        - env
                        - vault
                      description: Source type of the value
            client_secret:
              description: client_credentials client secret (redacted in responses)
              oneOf:
                - type: string
                  description: >-
                    Bare input form — plain text, `env.VAR_NAME`, or
                    `vault.path/to/secret`
                - type: object
                  description: Resolved form, as returned by GET responses
                  properties:
                    value:
                      type: string
                      description: >-
                        Resolved value (redacted in GET responses for secret
                        fields)
                    ref:
                      type: string
                      description: >-
                        Source reference (`env.VAR_NAME` or `vault.path`); empty
                        for plain-text values
                    type:
                      type: string
                      enum:
                        - plain_text
                        - env
                        - vault
                      description: Source type of the value
            private_key:
              description: jwt_bearer RSA or EC private key, PEM (redacted in responses)
              oneOf:
                - type: string
                  description: >-
                    Bare input form — plain text, `env.VAR_NAME`, or
                    `vault.path/to/secret`
                - type: object
                  description: Resolved form, as returned by GET responses
                  properties:
                    value:
                      type: string
                      description: >-
                        Resolved value (redacted in GET responses for secret
                        fields)
                    ref:
                      type: string
                      description: >-
                        Source reference (`env.VAR_NAME` or `vault.path`); empty
                        for plain-text values
                    type:
                      type: string
                      enum:
                        - plain_text
                        - env
                        - vault
                      description: Source type of the value
            scopes:
              type: array
              items:
                type: string
              description: Scopes requested, sent space-joined
            audience:
              type: string
              description: >-
                jwt_bearer aud claim (required for that grant);
                client_credentials optional audience form parameter
            issuer:
              type: string
              minLength: 1
              description: jwt_bearer iss claim (required for that grant)
            subject:
              type: string
              description: jwt_bearer sub claim (defaults to issuer)
            key_id:
              type: string
              description: jwt_bearer kid header
            signing_algorithm:
              type: string
              enum:
                - RS256
                - RS384
                - RS512
                - PS256
                - PS384
                - PS512
                - ES256
                - ES384
                - ES512
              default: RS256
              description: jwt_bearer assertion signing algorithm
            auth_style:
              type: string
              enum:
                - header
                - body
              default: header
              description: >-
                client_credentials credential placement (HTTP Basic header or
                form body)
            extra_params:
              type: object
              additionalProperties:
                type: string
              description: Extra form parameters sent on the token request
            assertion_lifetime_seconds:
              type: integer
              minimum: 0
              maximum: 3600
              default: 300
              description: >-
                jwt_bearer: seconds from issue until the assertion expires (exp
                = now + value); 0 or omitted uses the default of 300. iat is
                backdated by 30 seconds for clock skew, so the assertion's exp -
                iat span is this value plus 30.
          additionalProperties: false
          allOf:
            - if:
                required:
                  - grant_type
                properties:
                  grant_type:
                    const: client_credentials
              then:
                required:
                  - client_id
                  - client_secret
                description: client_credentials needs the client ID and secret
            - if:
                required:
                  - grant_type
                properties:
                  grant_type:
                    const: jwt_bearer
              then:
                required:
                  - private_key
                  - issuer
                  - audience
                properties:
                  audience:
                    minLength: 1
                description: >-
                  jwt_bearer needs the signing key plus the non-empty iss and
                  aud claims
        enabled:
          type: boolean
          description: Whether the key is active (defaults to true)
        use_for_batch_api:
          type: boolean
          description: Whether this key can be used for batch API operations
        config_hash:
          type: string
          description: Hash of config.json version, used for change detection
        status:
          type: string
          description: Status of key (e.g., success, list_models_failed)
        description:
          type: string
          description: Error or status description for the key
    BifrostError:
      type: object
      description: Error response from Bifrost
      properties:
        event_id:
          type: string
        type:
          type: string
        is_bifrost_error:
          type: boolean
        status_code:
          type: integer
        error:
          $ref: '#/components/schemas/ErrorField'
        extra_fields:
          $ref: '#/components/schemas/BifrostErrorExtraFields'
    ErrorField:
      type: object
      properties:
        type:
          type: string
        code:
          type: string
        message:
          type: string
        param:
          type: string
        event_id:
          type: string
    BifrostErrorExtraFields:
      type: object
      properties:
        routing_info:
          $ref: '#/components/schemas/RoutingInfo'
        provider:
          $ref: '#/components/schemas/ModelProvider'
          deprecated: true
          description: 'Deprecated: use routing_info.provider.'
        original_model_requested:
          type: string
          deprecated: true
          description: >-
            Deprecated: use routing_info.primary_model when
            routing_info.is_fallback is true, otherwise routing_info.model. For
            the model the caller asked for, read routing_info.requested_model.
        resolved_model_used:
          type: string
          deprecated: true
          description: >-
            Deprecated: use routing_info.resolved_key_alias.model_id when an
            alias matched, otherwise routing_info.model.
        request_type:
          type: string
        mcp_request_type:
          type: string
        a2a_request_type:
          type: string
          description: Agent Gateway operation, for A2A errors
        a2a_agent_name:
          type: string
        error_type:
          type: string
          description: >-
            Normalized, low-cardinality classification of why the request
            failed, declared by whichever component refused it. Prefixed by
            fault domain (caller_, policy_, provider_, bifrost_). Absent on
            failures that were not classified at source.
        retry_after_ms:
          type: integer
          format: int64
          minimum: 1000
          maximum: 300000
          description: >-
            The provider's hint for how long to wait before retrying, in
            milliseconds, read from its retry-after-ms or Retry-After header or
            its google.rpc.RetryInfo error detail, and clamped to between 1000
            and 300000. Absent when the provider gave no explicit hint.
        raw_request:
          description: Raw provider request, when raw request capture is enabled
        raw_response:
          description: Raw provider response, when raw response capture is enabled
        converted_request_type:
          type: string
        dropped_compat_plugin_params:
          type: array
          items:
            type: string
        latency:
          type: integer
          format: int64
          description: Latency in milliseconds
        key_statuses:
          type: array
          description: >-
            Per-key results, for requests that ran on every key such as listing
            models
          items:
            type: object
            properties:
              key_id:
                type: string
              status:
                type: string
                enum:
                  - success
                  - list_models_failed
              provider:
                $ref: '#/components/schemas/ModelProvider'
              error:
                $ref: '#/components/schemas/BifrostError'
        fallback_attempts:
          type: array
          description: >-
            Set when the primary and every fallback failed and the primary's
            error was returned: what became of each fallback, in chain order. A
            fallback refused before reaching its provider (for example by a
            virtual key that does not allow it) is only visible here.
          items:
            type: object
            properties:
              provider:
                $ref: '#/components/schemas/ModelProvider'
              model:
                type: string
              status_code:
                type: integer
              type:
                type: string
              message:
                type: string
              skipped:
                type: boolean
                description: >-
                  The fallback was never attempted (no provider config, or the
                  request type has no fallback support)
        mcp_auth_required:
          type: object
          description: >-
            Set when a per-user MCP tool needs the caller to complete an inline
            auth flow
          properties:
            kind:
              type: string
            mcp_client_id:
              type: string
            mcp_client_name:
              type: string
            message:
              type: string
            authorize_url:
              type: string
            session_id:
              type: string
            subject_token_missing:
              type: boolean
              description: >-
                token_exchange only. True when there was nothing to exchange,
                including when the caller's Bifrost sign-in has expired; message
                says which
            exchange_error:
              type: string
              description: >-
                token_exchange only. The identity provider's error code and
                description when it refused the exchange
        billed_usage:
          $ref: '#/components/schemas/BifrostLLMUsage'
          description: >-
            Usage the provider reported and billed even though the request
            failed
    RoutingInfo:
      type: object
      description: >-
        Which provider, model and key handled the attempt that produced this
        response or error, and what the caller asked for. Also sent as
        x-bifrost-routing-info-* response headers.
      properties:
        provider:
          $ref: '#/components/schemas/ModelProvider'
          description: Provider that ran the attempt
        model:
          type: string
          description: Model sent to that provider
        key:
          type: string
          description: Name of the stored key used, never its ID or secret
        resolved_key_alias:
          $ref: '#/components/schemas/ResolvedKeyAlias'
        is_fallback:
          type: boolean
          description: >-
            True when a fallback served the request or returned the error.
            Omitted when false.
        primary_provider:
          $ref: '#/components/schemas/ModelProvider'
          description: The primary attempt's provider. Set only when a fallback ran.
        primary_model:
          type: string
          description: The primary attempt's model. Set only when a fallback ran.
        requested_provider:
          $ref: '#/components/schemas/ModelProvider'
          description: >-
            Provider the caller asked for, before routing rules, load balancing
            or session affinity changed it. Omitted when the caller sent a bare
            model.
        requested_model:
          type: string
          description: Model the caller asked for, before anything changed it
        server_side_fallback_model:
          type: string
          description: Model that answered when Anthropic switched models inside one call
    ModelProvider:
      type: string
      description: AI model provider identifier
      enum:
        - anthropic
        - azure
        - bedrock
        - bedrock_mantle
        - sagemaker
        - cerebras
        - cohere
        - deepseek
        - gemini
        - groq
        - mistral
        - ollama
        - opencode-go
        - opencode-zen
        - openai
        - parasail
        - perplexity
        - sgl
        - vertex
        - openrouter
        - elevenlabs
        - huggingface
        - nebius
        - xai
        - replicate
        - vllm
        - runway
        - runware
        - fireworks
        - sarvam
        - wafer
        - databricks
        - cloudflare
        - typesafe
        - minimax
        - byteplus
    BifrostLLMUsage:
      type: object
      description: Token usage information
      properties:
        prompt_tokens:
          type: integer
          description: >
            Total input tokens including any prompt-cache tokens (read + write).
            Subtract prompt_tokens_details.cached_read_tokens and
            prompt_tokens_details.cached_write_tokens to get the non-cached
            portion.
        prompt_tokens_details:
          $ref: '#/components/schemas/ChatPromptTokensDetails'
        completion_tokens:
          type: integer
          description: Number of output/completion tokens generated.
        completion_tokens_details:
          $ref: '#/components/schemas/ChatCompletionTokensDetails'
        total_tokens:
          type: integer
        tool_usage:
          type: object
          description: |
            Counts of provider-hosted (server-side) tool calls billed per call.
          properties:
            web_search:
              type: object
              properties:
                num_requests:
                  type: integer
                  description: Number of billable web search calls.
        cost:
          $ref: '#/components/schemas/BifrostCost'
    ResolvedKeyAlias:
      type: object
      description: Set only when the requested model matched a model alias on the key
      required:
        - model_id
      properties:
        model_id:
          type: string
          description: Model ID sent to the provider
        model_name:
          type: string
          description: Canonical model name, used for pricing and logs
        model_family:
          type: string
          description: Resolved model family
    ChatPromptTokensDetails:
      type: object
      properties:
        text_tokens:
          type: integer
        audio_tokens:
          type: integer
        image_tokens:
          type: integer
        cached_read_tokens:
          type: integer
          description: >
            Tokens served from the prompt cache (cache hit). These tokens are
            already included in prompt_tokens and are billed at the reduced
            cache-read rate. Populated for all providers that support prompt
            caching (Anthropic, Bedrock, OpenAI, Gemini, xAI, etc.).
        cached_write_tokens:
          type: integer
          description: >
            Tokens written to the prompt cache on this request (cache creation /
            write). These tokens are already included in prompt_tokens and are
            billed at the cache-creation rate. Populated for providers that
            separately report cache write tokens (Anthropic, Bedrock).
    ChatCompletionTokensDetails:
      type: object
      properties:
        text_tokens:
          type: integer
        accepted_prediction_tokens:
          type: integer
        audio_tokens:
          type: integer
        citation_tokens:
          type: integer
        num_search_queries:
          type: integer
          deprecated: true
          description: >-
            Deprecated, use tool_usage.web_search.num_requests. Will be removed
            in 3.0.0.
        reasoning_tokens:
          type: integer
        image_tokens:
          type: integer
        rejected_prediction_tokens:
          type: integer
    BifrostCost:
      type: object
      description: Cost breakdown for the request
      properties:
        input_tokens_cost:
          type: number
        output_tokens_cost:
          type: number
        reasoning_tokens_cost:
          type: number
          description: Cost for reasoning/thinking tokens (reasoning models)
        citation_tokens_cost:
          type: number
          description: Cost for citation tokens
        search_queries_cost:
          type: number
          description: Cost for web search queries
        request_cost:
          type: number
        total_cost:
          type: number
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: >
        Bearer token authentication. Use your provider API key or Bifrost
        authentication token.

        Virtual keys (prefixed with `sk-bf-`) can also be passed here.
    BasicAuth:
      type: http
      scheme: basic
      description: >
        Basic authentication using the Bifrost admin username and password

        (`auth_config.admin_username` / `auth_config.admin_password`).

        Accepted on management APIs (`/api/*`, `/metrics`, `/ws`) only - the
        inference

        middleware never validates Basic credentials.
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: |
        API key authentication via the `x-api-key` header.
        Virtual keys (prefixed with `sk-bf-`) can also be passed here.
    ManagementBearerAuth:
      type: http
      scheme: bearer
      description: >
        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 of
        `BasicAuth`).


        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](/api/procuring-api-keys#required-permissions)
        for how

        permissions are derived and which endpoints are exempt.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.