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": 123,
        "allowed_models": [
          "<string>"
        ],
        "blacklisted_models": [
          "<string>"
        ],
        "allow_all_keys": true,
        "keys": [
          {
            "id": 123,
            "name": "<string>",
            "provider_id": 123,
            "provider": "<string>",
            "key_id": "<string>",
            "value": {
              "value": "<string>",
              "ref": "<string>",
              "type": "plain_text"
            },
            "models": [
              "<string>"
            ],
            "weight": 123,
            "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": {
              "value": "<string>",
              "ref": "<string>",
              "type": "plain_text"
            },
            "azure_client_id": {
              "value": "<string>",
              "ref": "<string>",
              "type": "plain_text"
            },
            "azure_client_secret": {
              "value": "<string>",
              "ref": "<string>",
              "type": "plain_text"
            },
            "azure_tenant_id": {
              "value": "<string>",
              "ref": "<string>",
              "type": "plain_text"
            },
            "vertex_project_id": {
              "value": "<string>",
              "ref": "<string>",
              "type": "plain_text"
            },
            "vertex_project_number": {
              "value": "<string>",
              "ref": "<string>",
              "type": "plain_text"
            },
            "vertex_region": {
              "value": "<string>",
              "ref": "<string>",
              "type": "plain_text"
            },
            "vertex_auth_credentials": {
              "value": "<string>",
              "ref": "<string>",
              "type": "plain_text"
            },
            "bedrock_access_key": {
              "value": "<string>",
              "ref": "<string>",
              "type": "plain_text"
            },
            "bedrock_secret_key": {
              "value": "<string>",
              "ref": "<string>",
              "type": "plain_text"
            },
            "bedrock_session_token": {
              "value": "<string>",
              "ref": "<string>",
              "type": "plain_text"
            },
            "bedrock_region": {
              "value": "<string>",
              "ref": "<string>",
              "type": "plain_text"
            },
            "bedrock_arn": {
              "value": "<string>",
              "ref": "<string>",
              "type": "plain_text"
            }
          }
        ],
        "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
            },
            "calendar_aligned": false,
            "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>"
            ]
          },
          "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
        },
        "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>",
    "expires_at": "2023-11-07T05:31:56Z",
    "team_id": "<string>",
    "customer_id": "<string>",
    "rate_limit_id": "<string>",
    "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
          },
          "calendar_aligned": false,
          "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
          },
          "calendar_aligned": false,
          "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
        },
        "calendar_aligned": false,
        "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
        },
        "calendar_aligned": false,
        "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>"
    },
    "created_by_user_id": "<string>"
  }
}

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.

Body

application/json

Create virtual key request

name · string · required

description · string

provider_configs · object[]

Provider configurations (empty means no providers allowed, deny-by-default)

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

Show child attributes

rate_limit · object

Create rate limit request

Show child attributes

is_active · boolean

calendar_aligned · boolean · default: false

expires_at · string<date-time>

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

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