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.
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
- Press Create API key.
- Name it after who or what uses it: a person, a laptop, a CI job (
alice-laptop). Requests are searchable by this name. - Pick the key group.
- Open the optional settings if you need them (below), and create.
- 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. |
Related
- Sign in: keys made by
venom cloud login. - Organisations, members and roles
- Venom Cloud quickstart