Update a virtual key

PUT/v1/virtual-keys/{slug}

Update a virtual key.

Changes the key's name, note, expiry, metadata, model allowlist, guardrails, credit settings and rate limits. The credential mode, provider keys, organization and workspace cannot be changed here (move a key with "Transfer a virtual key"; for other provider keys, create a new key).

How each field is applied:

name, note and credit_reset_policy change when present and are kept when left out. Setting credit_reset_policy also schedules its next reset from now.
The limits credit_limit_usd, credit_alert_threshold_usd, rate_limit_rpm, rate_limit_tpm and rate_limit_rpd: a number sets the limit, null removes it, and leaving the field out keeps it.
guardrail_slugs: a list replaces the attached guardrails ([] detaches them all); leaving it out keeps them.
expires_at, metadata and model_allowlist: a value replaces it, null removes it (the key no longer expires, has no metadata, or may call every model), and leaving the field out keeps it.

When the credit limit changes, the status follows it: an EXHAUSTED key whose limit is removed, or raised above what it has spent, becomes ACTIVE; an ACTIVE key whose limit is lowered to what it has spent, or below, becomes EXHAUSTED. DISABLED and EXPIRED keys keep their status.

Requires an organization admin key, or a workspace admin key for the key's workspace.

Errors: 400 for a body that does not match the schema, or a guardrail slug that is unknown, duplicated or in another workspace; 403 without the required role; 404 when no key has this slug.

Authorization

AuthorizationBearer va_
A platform API key (va_...), created under Settings > API keys. Scoped to an organization or one workspace, with an admin or member role. Used by the management API.

Path parameters

slugstringrequired
the key's slug

Request body application/json

the fields to change

namestring
The key's new name. Left out or null: unchanged.
notestring
The key's new note. Left out or null: unchanged.
expires_atstring<date-time>
When the key expires (ISO 8601 date-time). null: the key no longer expires. Left out: unchanged.
metadatamap<string, string>
Your own string key/value pairs, replacing the current ones. null or {} clears them. Left out: unchanged.
model_allowliststring[]
The models the key may call (see the key's model_allowlist), replacing the current list. null or [] allows every model. Left out: unchanged.
guardrail_slugsstring[]
Slugs of the guardrails to run on the key's requests. A list replaces the attached guardrails, [] detaches them all; left out or null: unchanged. Each must belong to the key's organization and, when it belongs to a workspace, to the key's workspace; no duplicates.
credit_limit_usdnumber<double>
The most the key may spend, in USD. A number sets it, null removes the limit, left out: unchanged. The key's status follows the new limit (ACTIVE or EXHAUSTED).
credit_alert_threshold_usdnumber<double>
The soft spend alert, in USD. A number sets it, null removes it, left out: unchanged.
credit_reset_policyenum<string>
When the key's spend goes back to zero: MONTHLY, WEEKLY or NEVER. Setting it schedules the next reset from now. Left out or null: unchanged.
One of "MONTHLY", "WEEKLY", "NEVER"
rate_limit_rpminteger<int32>
Requests per minute. A number sets the limit, null removes it, left out: unchanged.
rate_limit_tpminteger<int32>
Tokens per minute. A number sets the limit, null removes it, left out: unchanged.
rate_limit_rpdinteger<int32>
Requests per UTC day. A number sets the limit, null removes it, left out: unchanged.

Responses

200application/json

slugstring
The key's stable identifier: vk- followed by 16 hex characters. Used in URLs, logs and routing configs.
token_hintstring
The last characters of the API key's secret, to tell keys apart. Absent for a key with legacy_auth.
legacy_authboolean
True for a key created before API keys existed: its bare slug still authenticates, until the key is rotated for the first time.
rotated_atstring<date-time>
When the API key was last rotated (ISO 8601 date-time). Absent if it never was.
namestring
The key's name, unique within the organization.
notestring
A free-text note about the key. Absent when none was set.
statusenum<string>
The key's status:
- ACTIVE: requests are served.
- DISABLED: turned off by an admin; requests are refused (403) until it is enabled.
- EXHAUSTED: its spend reached credit_limit_usd; requests are refused (403) until the limit is raised or removed, the spend resets (credit_reset_policy) or, for a PLATFORM key, credit is added.
- EXPIRED: past expires_at; final.
One of "ACTIVE", "DISABLED", "EXHAUSTED", "EXPIRED"
disable_reasonstring
The reason given when the key was disabled. Absent unless the key is DISABLED with a reason.
credential_modeenum<string>
Where the provider credentials come from: BYOK (your provider keys, in credentials) or PLATFORM (VectorAxis's provider accounts, paid from your organization's credits).
One of "BYOK", "PLATFORM"
credentialsobject[]
The key's provider credentials, as hints only. Empty for a PLATFORM key.
Child attributes
- providerstring
  The provider id, e.g. OPENAI (see "List supported providers").
- key_hintstring
  The last four characters of the provider key, to tell keys apart.
- vertex_project_idstring
  For a VERTEX_AI credential: the Google Cloud project id. Absent for other providers.
- vertex_regionstring
  For a VERTEX_AI credential: the Vertex AI region, or global. Absent for other providers.
organizationstring
The slug of the organization the key belongs to.
workspace_idstring<uuid>
The workspace the key belongs to (UUID).
created_atstring<date-time>
When the key was created (ISO 8601 date-time).
updated_atstring<date-time>
When the key's settings or status last changed (ISO 8601 date-time).
expires_atstring<date-time>
When the key expires (ISO 8601 date-time). Absent: it never expires.
last_used_atstring<date-time>
When the key last served a request (ISO 8601 date-time). Absent if it never has.
total_requestsinteger<int64>
How many requests the key has served.
total_cost_usdnumber<double>
What the key has spent, in USD, since it was created or since its last credit reset. This is the figure credit_limit_usd and credit_alert_threshold_usd are compared with.
metadatamap<string, string>
Your own string key/value pairs. Absent when none are set.
model_allowliststring[]
The models the key may call; others are refused (403 MODEL_NOT_ALLOWED). Absent: every model.
credit_limit_usdnumber<double>
The most the key may spend, in USD, before it becomes EXHAUSTED. Absent: no limit.
credit_alert_threshold_usdnumber<double>
The soft spend alert, in USD: at or above it the key carries the ALERT_THRESHOLD_EXCEEDED warning. Absent: no alert.
credit_reset_policyenum<string>
When the key's spend goes back to zero: MONTHLY (the 1st of each month, 00:00 UTC), WEEKLY (each Monday, 00:00 UTC) or NEVER.
One of "MONTHLY", "WEEKLY", "NEVER"
credit_next_reset_atstring<date-time>
When the next credit reset is due (ISO 8601 date-time). Absent when the policy is NEVER.
rate_limit_rpminteger<int32>
The most requests per minute (a 60-second window). Absent: no limit.
rate_limit_tpminteger<int32>
The most tokens per minute (a 60-second window). Absent: no limit.
rate_limit_rpdinteger<int32>
The most requests per UTC calendar day. Absent: no limit.
initial_credits_usdnumber<double>
For a PLATFORM key: the credit in USD it was created with. Absent for a BYOK key.
credit_balance_usdnumber<double>
For a PLATFORM key: what it may still spend, in USD (credit_limit_usd minus total_cost_usd). Absent for a BYOK key, or when there is no limit.
provider_whiteliststring[]
For a PLATFORM key: the only providers it may use, as provider ids. Absent: any provider.
guardrail_slugsstring[]
Slugs of the guardrails run on every request made with the key. Absent: none.
markup_pctnumber<double>
For a PLATFORM key: its own markup on the provider's price, as a fraction (0.06 is 6%). Absent: the platform default markup applies.
warningsenum<string>[]
Advisory warnings, computed when the key is read; they never block requests:
- ALERT_THRESHOLD_EXCEEDED: total_cost_usd has reached credit_alert_threshold_usd.
- EXPIRING_SOON: the key expires within the next few days.
Empty when there is nothing to report.

Request

curl -X PUT "https://api.vectoraxis.ai/v1/virtual-keys/{slug}" \
  -H "Authorization: Bearer $VECTORAXIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "string",
  "note": "string",
  "expires_at": "2026-01-15T09:30:00Z",
  "metadata": {
    "key": "string"
  },
  "model_allowlist": [
    "string"
  ],
  "guardrail_slugs": [
    "string"
  ],
  "credit_limit_usd": 0,
  "credit_alert_threshold_usd": 0,
  "credit_reset_policy": "MONTHLY",
  "rate_limit_rpm": 0,
  "rate_limit_tpm": 0,
  "rate_limit_rpd": 0
}'

VectorAxis is built by GK Labs, a member of NVIDIA Inception.