Update virtual key

Updates an existing virtual key’s configuration.

PUT /api/governance/virtual-keys/{vk_id}

Error

A valid request URL is required to generate request examples

200

{
  "message": "<string>",
  "virtual_key": {
    "id": "<string>",
    "name": "<string>",
    "value": "<string>",
    "is_active": true,
    "provider_configs": [
      {
        "id": 123,
        "virtual_key_id": "<string>",
        "provider": "<string>",
        "weight": 1,
        "allowed_models": [
          "<string>"
        ],
        "blacklisted_models": [
          "<string>"
        ],
        "allow_all_keys": true,
        "keys": [
          {
            "id": 123,
            "name": "<string>",
            "provider_id": 123,
            "provider": "<string>",
            "key_id": "<string>",
            "value": "<string>",
            "models": [
              "<string>"
            ],
            "weight": 1,
            "enabled": true,
            "use_for_batch_api": false,
            "created_at": "2023-11-07T05:31:56Z",
            "updated_at": "2023-11-07T05:31:56Z",
            "config_hash": "<string>",
            "azure_endpoint": "<string>",
            "azure_client_id": "<string>",
            "azure_client_secret": "<string>",
            "azure_tenant_id": "<string>",
            "vertex_project_id": "<string>",
            "vertex_project_number": "<string>",
            "vertex_region": "<string>",
            "vertex_auth_credentials": "<string>",
            "bedrock_access_key": "<string>",
            "bedrock_secret_key": "<string>",
            "bedrock_session_token": "<string>",
            "bedrock_region": "<string>",
            "bedrock_arn": "<string>"
          }
        ],
        "rate_limit_id": "<string>",
        "budgets": [
          {
            "id": "<string>",
            "max_limit": 123,
            "reset_duration": "<string>",
            "last_reset": "2023-11-07T05:31:56Z",
            "current_usage": 123,
            "config_hash": "<string>",
            "created_at": "2023-11-07T05:31:56Z",
            "updated_at": "2023-11-07T05:31:56Z",
            "reset_config": {
              "quarter_start_month": 6
            },
            "override_amount": 123,
            "override_mode": "cycles",
            "override_cycles_remaining": 123,
            "override_cycles_total": 123,
            "override_anchor_reset": "2023-11-07T05:31:56Z",
            "team_id": "<string>",
            "virtual_key_id": "<string>",
            "provider_config_id": 123
          }
        ],
        "rate_limit": {
          "id": "<string>",
          "token_current_usage": 123,
          "token_last_reset": "2023-11-07T05:31:56Z",
          "request_current_usage": 123,
          "request_last_reset": "2023-11-07T05:31:56Z",
          "config_hash": "<string>",
          "created_at": "2023-11-07T05:31:56Z",
          "updated_at": "2023-11-07T05:31:56Z",
          "token_max_limit": 123,
          "token_reset_duration": "<string>",
          "request_max_limit": 123,
          "request_reset_duration": "<string>"
        }
      }
    ],
    "mcp_configs": [
      {
        "id": 123,
        "virtual_key_id": "<string>",
        "mcp_client_id": 123,
        "mcp_client": {
          "client_id": "<string>",
          "name": "<string>",
          "is_code_mode_client": true,
          "connection_type": "http",
          "connection_string": "<string>",
          "stdio_config": {
            "command": "<string>",
            "args": [
              "<string>"
            ],
            "envs": [
              "<string>"
            ]
          },
          "openapi_config": {
            "spec": "<string>",
            "spec_url": "<string>",
            "base_url": "<string>",
            "security_credentials": {},
            "include_deprecated": false,
            "max_response_bytes": 1,
            "spec_size": 123,
            "spec_hash": "<string>",
            "spec_title": "<string>",
            "openapi_version": "<string>",
            "operation_count": 123
          },
          "tls_config": {
            "insecure_skip_verify": true,
            "ca_cert_pem": "<string>"
          },
          "auth_type": "none",
          "oauth_config_id": "<string>",
          "headers": {},
          "tools_to_execute": [
            "<string>"
          ],
          "tools_to_auto_execute": [
            "<string>"
          ],
          "tool_pricing": {},
          "allow_on_all_virtual_keys": false,
          "per_user_header_keys": [
            "<string>"
          ],
          "token_exchange": {
            "audience": "<string>",
            "use_idp_credentials": true,
            "client_id": "<string>",
            "client_secret": "<string>",
            "scopes": [
              "<string>"
            ],
            "authorization_server_url": "<string>"
          },
          "disabled": false,
          "require_public_target": false
        },
        "tools_to_execute": [
          "<string>"
        ]
      }
    ],
    "calendar_aligned": true,
    "config_hash": "<string>",
    "created_at": "2023-11-07T05:31:56Z",
    "updated_at": "2023-11-07T05:31:56Z",
    "description": "<string>",
    "metadata": {},
    "expires_at": "2023-11-07T05:31:56Z",
    "delete_after_expire": true,
    "previous_value_expires_at": "2023-11-07T05:31:56Z",
    "rotated_at": "2023-11-07T05:31:56Z",
    "team_id": "<string>",
    "customer_id": "<string>",
    "rate_limit_id": "<string>",
    "allow_all_providers": true,
    "disable_content_logging": true,
    "team": {
      "id": "<string>",
      "name": "<string>",
      "customer_id": "<string>",
      "customer": {
        "id": "<string>",
        "name": "<string>",
        "budget_id": "<string>",
        "budget": {
          "id": "<string>",
          "max_limit": 123,
          "reset_duration": "<string>",
          "last_reset": "2023-11-07T05:31:56Z",
          "current_usage": 123,
          "config_hash": "<string>",
          "created_at": "2023-11-07T05:31:56Z",
          "updated_at": "2023-11-07T05:31:56Z",
          "reset_config": {
            "quarter_start_month": 6
          },
          "override_amount": 123,
          "override_mode": "cycles",
          "override_cycles_remaining": 123,
          "override_cycles_total": 123,
          "override_anchor_reset": "2023-11-07T05:31:56Z",
          "team_id": "<string>",
          "virtual_key_id": "<string>",
          "provider_config_id": 123
        },
        "teams": "<array>",
        "virtual_keys": "<array>",
        "virtual_key_count": 123,
        "config_hash": "<string>",
        "created_at": "2023-11-07T05:31:56Z",
        "updated_at": "2023-11-07T05:31:56Z"
      },
      "budgets": [
        {
          "id": "<string>",
          "max_limit": 123,
          "reset_duration": "<string>",
          "last_reset": "2023-11-07T05:31:56Z",
          "current_usage": 123,
          "config_hash": "<string>",
          "created_at": "2023-11-07T05:31:56Z",
          "updated_at": "2023-11-07T05:31:56Z",
          "reset_config": {
            "quarter_start_month": 6
          },
          "override_amount": 123,
          "override_mode": "cycles",
          "override_cycles_remaining": 123,
          "override_cycles_total": 123,
          "override_anchor_reset": "2023-11-07T05:31:56Z",
          "team_id": "<string>",
          "virtual_key_id": "<string>",
          "provider_config_id": 123
        }
      ],
      "virtual_keys": "<array>",
      "profile": {},
      "config": {},
      "claims": {},
      "config_hash": "<string>",
      "created_at": "2023-11-07T05:31:56Z",
      "updated_at": "2023-11-07T05:31:56Z"
    },
    "customer": {
      "id": "<string>",
      "name": "<string>",
      "budget_id": "<string>",
      "budget": {
        "id": "<string>",
        "max_limit": 123,
        "reset_duration": "<string>",
        "last_reset": "2023-11-07T05:31:56Z",
        "current_usage": 123,
        "config_hash": "<string>",
        "created_at": "2023-11-07T05:31:56Z",
        "updated_at": "2023-11-07T05:31:56Z",
        "reset_config": {
          "quarter_start_month": 6
        },
        "override_amount": 123,
        "override_mode": "cycles",
        "override_cycles_remaining": 123,
        "override_cycles_total": 123,
        "override_anchor_reset": "2023-11-07T05:31:56Z",
        "team_id": "<string>",
        "virtual_key_id": "<string>",
        "provider_config_id": 123
      },
      "teams": "<array>",
      "virtual_keys": "<array>",
      "virtual_key_count": 123,
      "config_hash": "<string>",
      "created_at": "2023-11-07T05:31:56Z",
      "updated_at": "2023-11-07T05:31:56Z"
    },
    "budgets": [
      {
        "id": "<string>",
        "max_limit": 123,
        "reset_duration": "<string>",
        "last_reset": "2023-11-07T05:31:56Z",
        "current_usage": 123,
        "config_hash": "<string>",
        "created_at": "2023-11-07T05:31:56Z",
        "updated_at": "2023-11-07T05:31:56Z",
        "reset_config": {
          "quarter_start_month": 6
        },
        "override_amount": 123,
        "override_mode": "cycles",
        "override_cycles_remaining": 123,
        "override_cycles_total": 123,
        "override_anchor_reset": "2023-11-07T05:31:56Z",
        "team_id": "<string>",
        "virtual_key_id": "<string>",
        "provider_config_id": 123
      }
    ],
    "rate_limit": {
      "id": "<string>",
      "token_current_usage": 123,
      "token_last_reset": "2023-11-07T05:31:56Z",
      "request_current_usage": 123,
      "request_last_reset": "2023-11-07T05:31:56Z",
      "config_hash": "<string>",
      "created_at": "2023-11-07T05:31:56Z",
      "updated_at": "2023-11-07T05:31:56Z",
      "token_max_limit": 123,
      "token_reset_duration": "<string>",
      "request_max_limit": 123,
      "request_reset_duration": "<string>"
    },
    "assigned_user": {
      "id": "<string>",
      "name": "<string>",
      "email": "<string>"
    },
    "created_by_user_id": "<string>"
  }
}

Required Permissions

Permission	Granted via
VirtualKeys:Update	RBAC role or API key scope

How permissions work

Authorizations

ManagementBearerAuthBasicAuth

Authorization · string · header · required

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 for how permissions are derived and which endpoints are exempt.

Path Parameters

vk_id · string · required

Virtual key ID

Body

application/json

Update virtual key request

name · string

description · string

metadata · object | null

Replaces the key's metadata as a whole. Omit (or send null) to leave it unchanged; send {} to clear it. Keys are 1-256 characters of letters, digits, '.', '' and '-' and may not be system-reserved (isAsyncRequest, bifrost_alb*); values are strings of at most 512 characters; at most 50 entries.

Show child attributes

provider_configs · object[]

Show child attributes

mcp_configs · object[]

Show child attributes

team_id · string

customer_id · string

budgets · object[]

Budget quotas assigned directly to this virtual key. Replaces all direct virtual-key budgets when provided; the removed singular budget and budget_id fields are not request fields.

Show child attributes

rate_limit · object

Update rate limit request

Show child attributes

is_active · boolean

calendar_aligned · boolean

allow_all_providers · boolean

When true, this virtual key may use every configured provider. provider_configs remain optional per-provider overrides. Omit to leave the current setting unchanged.

disable_content_logging · boolean | null

Tri-state. Omit to leave the current decision unchanged, null to clear it back to inheriting client.disable_content_logging, true to keep content out of the log store and out of OpenTelemetry export (other observability connectors follow their own disable_content_logging until they adopt the trace mark), false to force content into the log store. When content logging ends up disabled for a request, the log row is still written without content; with client.retain_content_in_object_storage on and an object-storage-backed log store, the full payload is then kept there as hidden content that the API and UI never serve. When client.allow_per_request_content_storage_override is on, the x-bf-disable-content-logging request header still takes precedence over this value for the log store.

reset_budget_usage · boolean

When true, zeroes current usage on the budgets reconciled by this update. The reset window is left alone: last_reset only ever advances, and never as a side effect of a configuration write, so the current window keeps its existing start and end.

expires_at · string

RFC3339 timestamp to set a new expiry (must be in the future), empty string to clear an existing expiry, omitted to leave it unchanged.

delete_after_expire · boolean | null

Override client.delete_expired_virtual_keys for this key. true or false set it, null resets the key to inherit the client setting, omitted leaves it unchanged. A value requires an expiry; clearing expires_at resets it to inherit.

Response

200

application/json

Virtual key updated successfully

Virtual key operation response

message · string · required

virtual_key · object · required

Virtual key configuration

Show child attributes