List virtual keys

Returns a list of all virtual keys with their configurations.

Metadata filters: add one metadata_<key>=<value> query parameter per metadata key to match, where <key> is the metadata key itself (for example ?metadata_cost_center=cc-42&metadata_environment=prod). Only virtual keys whose metadata has every given key set to exactly the given value are returned. A key that is not 1-256 characters of letters, digits, ’.’, ’_’ and ’-’ is rejected with a 400. These parameters have dynamic names, so they are described here rather than declared as individual parameters.

GET /api/governance/virtual-keys

Error

A valid request URL is required to generate request examples

200

{
  "virtual_keys": [
    {
      "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>"
    }
  ],
  "count": 123,
  "total_count": 123,
  "limit": 123,
  "offset": 123
}

Required Permissions

Permission	Granted via
VirtualKeys:View	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.

Query Parameters

from_memory · boolean · default: false

If true, returns virtual keys from in-memory cache instead of database. Filtering, sorting and pagination parameters are not applied in this mode; combining it with user_id is rejected with a 400.

limit · integer

Maximum number of virtual keys to return

Required range: x >= 0

offset · integer

Number of virtual keys to skip

Required range: x >= 0

search · string

Case-insensitive search across the virtual key name, its team name, its customer name, and its metadata keys and values. Enterprise additionally matches the name and email of the user the key is assigned to.

customer_id · string

Filter virtual keys by customer ID

team_id · string

Filter virtual keys by team ID

user_id · string

Filter virtual keys by assigned user ID (enterprise only; matches no virtual keys on OSS builds). Combined with customer_id/team_id using OR.

sort_by · enum<string>

Field to sort by

Available options: name, budget_spent, created_at, status

order · enum<string>

Sort order

Available options: asc, desc

export · boolean · default: false

If true, enables export pagination limits

exclude_access_profile_managed_virtual · boolean · default: false

If true, excludes virtual keys managed by access profiles

Response

200

application/json

Successful response

List virtual keys response

virtual_keys · object[] · required

Show child attributes

count · integer · required

total_count · integer<int64> · required

Total number of virtual keys matching the query

limit · integer · required

Page size used for the response

offset · integer · required

Page offset used for the response