Skip to content
Docs menu

API keys and key rotation

Create vck_ API keys for the venom CLI, scripts and OpenAI SDKs, scope them by model, budget, rate and expiry, rotate, pause and revoke them, and set the organisation's key rotation schedule.

View .md

An API key (vck_…) lets the venom CLI, a script, a CI job or any OpenAI SDK call this cloud's OpenAI-compatible /v1. Each key belongs to a key group: it spends from that key group's budget and routes to its daemons and providers. A key group holds API keys, daemons, policies and GPU grants, not people; the API calls it team (team_id). Keys are managed at /settings/keys (Settings, API keys); the rotation schedule for both API keys and provider keys is at /settings/key-rotation.

Action Needs
See keys keys:read (every role but billing)
Create, edit, rotate, revoke keys:write (owner, admin, developer)
Pause and resume keys:write or billing:manage
Model access by role org:manage (owner, admin)
Key group admin keys (vak_) the operator

venom cloud login makes keys too, named after the machine (see Sign in); they show in the same list.

Create a key

  1. Press Create API key.
  2. Name it after who or what uses it: a person, a laptop, a CI job (alice-laptop). Requests are searchable by this name.
  3. Pick the key group.
  4. Open the optional settings if you need them (below), and create.
  5. Copy the key now. The dialog shows it once, with how to use it. A lost key can't be shown again: revoke it and make another.
curl https://cloud.usevenom.dev/v1/chat/completions \
  -H "Authorization: Bearer vck_…" \
  -H "Content-Type: application/json" \
  -d '{"model":"venom-auto","messages":[{"role":"user","content":"Reply with: ready"}]}'

Key settings

All optional; none by default.

Field Default What it does
Name required who or what uses the key
Key group required the key group the key spends from and routes to
Kind API key (vck_) operator only: key group admin key (vak_), which manages one key group through the admin API and cannot call /v1
This key is mine off your personal guardrails apply to it; leave it off for a shared or service key, which gets only the organisation's and key group's guardrails
Allowed models any only these, when set; * matches any run of characters (openai/*). List a gear's models to scope the key to it
Denied models none never these, whatever else allows them (*-preview)
Expires (UTC) never the key stops working at this time
Project none for chargeback: requests without an x-venom-project header count toward this project
Requests / min unlimited rate limit
Tokens / min unlimited token rate limit
Daily budget (USD) none spend per day
Monthly cap (USD) none spend per month
Prefer Any Own daemons: your daemons first, the cloud's providers after; Any: cheapest, fastest
Sovereign only off never use a cloud provider: your daemons or nothing

The model fields pick from the models your organisation serves now.

Manage keys

Each row shows the key's prefix, key group, limits, expiry and this month's spend. Its "…" menu:

Action What happens
View requests opens Requests filtered to this key's name
Edit change allowed and denied models, expiry, budget and project; takes effect within 10 seconds
Rotate a new key replaces this one, with the same name, models, limits and budget; the new key is shown once and the old one keeps working for 24 hours, then expires. The link is /settings/keys?rotate=<id>
Pause requests with the key get 403 key_paused within 10 seconds, until resumed; nothing is lost
Resume undoes a pause
Revoke requests start failing with 401 within 10 seconds; a revoked key can't be restored

Rotated and expired keys can't be rotated again. Keys a removed member made keep working until you revoke them, unless single sign-on's key policy revoked or paused them (see Single sign-on and SCIM).

Model access by role

"Model access by role" sets allowed and denied models for every key that a member with a given role created, on top of each key's own lists. Edit one role at a time. For example, give viewer keys only openai/* and venom-fast, or deny *-preview to developer keys. A key's own denied list and its creator's role can deny more; neither can allow what the other denies.

Key rotation schedule

/settings/key-rotation says when to rotate the organisation's provider keys and API keys, and lists every live key against the schedule, most urgent first. Reading it needs providers:read (API keys also need keys:read). Nothing on the page calls a provider.

Field Default Choices Needs
Provider keys every 90 days 30, 60, 90, 180, 365 days, or never (any 1 to 3,650 days through the API); counted from when the current key was added providers:write
Old key keeps serving 24 hours retire at once, 1 hour, 24 hours, 3 days, 7 days (at most 30 days through the API); after a rotation, behind the new key providers:write
API keys (vck_) never the same day choices; counted from when the key was made keys:write

A key is "due" 14 days before its date and "overdue" after it. Reminders go to the console's notification bell and to webhooks that take key_rotation events, and follow a new schedule within a minute. Provider keys rotate on their provider's page (the new key serves first, the old one behind it until the grace ends); API keys rotate from the "…" menu above. A role that can see the schedule but not change it sees the fields disabled.

Troubleshooting

Symptom Cause and fix
401 from /v1 The key is wrong, revoked or expired. Check its row; make a new one.
403 key_paused Someone paused the key. Resume it from its menu.
403 model_not_allowed The model is outside the key's allowed list, in its denied list, or denied for its creator's role.
429 rate_limit_exceeded, tpm_limit_exceeded The key's requests or tokens per minute ran out; retry after the retry-after header.
429 budget_exceeded The key's daily budget or monthly cap is spent. Raise it under Edit, or wait for the next day or month.
"Pick a key group and name the key." Both fields are required.
"The expiry is not a valid time." Use a full date and time, in UTC.
"A key belongs to a key group. The operator creates key groups under Tenants & key groups." The organisation has no key group yet.