Skip to main content
GET
Error
Required Permissions How permissions work

Authorizations

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
default:25

Page size, 0 to 100 (default 25). Values above 100 are clamped to 100 without an error, and 0 uses the default, so read limit back from the response. Page with offset until offset >= total_count. With export=true the bound is 10,000 and the default is 10,000.

Required range: 0 <= x <= 100
offset
integer
default:0

Number of virtual keys to skip

Required range: x >= 0

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

business_unit_id
string

Filter virtual keys by owning business unit ID. Combined with customer_id/team_id/user_id using OR.

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/business_unit_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, uses the export page bounds: limit defaults to 10,000 and is capped at 10,000 instead of 100.

exclude_access_profile_managed_virtual
boolean
default:false

If true, excludes virtual keys managed by access profiles

exclude_assigned_virtual_keys
boolean
default:false

If true, excludes virtual keys that already have a user assignment (enterprise only; ignored on OSS builds).

for_user_assignment
boolean
default:false

If true, excludes virtual keys assigned to any team, customer, access profile or user, for user-assignment pickers (enterprise only; ignored on OSS builds).

Response

Successful response

List virtual keys response

virtual_keys
object[]
required
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