Create virtual key

Creates a new virtual key with the specified configuration.

POST /api/governance/virtual-keys

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:Create	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.

Body

application/json

Create virtual key request

name · string · required

description · string

metadata · object

Custom key/value metadata for cost attribution (for example cost_center, project, owner, environment). 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[]

Provider configurations. When allow_all_providers is omitted or false, an empty list allows no providers (deny-by-default); when true, providers without a config are allowed with all models and keys.

Show child attributes

mcp_configs · object[]

MCP configurations (empty means no MCP tools allowed, deny-by-default)

Show child attributes

team_id · string

customer_id · string

budgets · object[]

Budget quotas assigned directly to this virtual key. Use this array instead of the removed singular budget or budget_id fields.

Show child attributes

rate_limit · object

Create rate limit request

Show child attributes

is_active · boolean

calendar_aligned · boolean · default: false

allow_all_providers · boolean · default: false

When true, this virtual key may use every configured provider. provider_configs remain optional per-provider overrides for budgets, rate limits, model allow/blacklists, and key selection.

disable_content_logging · boolean | null

The key's own content-logging decision. Omit or set null to inherit client.disable_content_logging. true keeps content out of the log store and out of OpenTelemetry export for this key's traffic (other observability connectors follow their own disable_content_logging until they adopt the trace mark); false forces content into the log store even when the client setting is true. 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.

expires_at · string<date-time>

Optional expiry timestamp. Must be in the future. Omit for a key that never expires.

delete_after_expire · boolean

Override client.delete_expired_virtual_keys for this key. Omit to inherit the client setting. Rejected with 400 when expires_at is not set.

Response

200

application/json

Virtual key created successfully

Virtual key operation response

message · string · required

virtual_key · object · required

Virtual key configuration

Show child attributes