Admin API: orgs, members and keys
Script your Venom Cloud org over /api/admin/v1 — orgs, key groups, members, client keys, join tokens, CLI logins, single sign-on, org settings, signed key group policies and onboarding paths.
These routes manage who can use an org and with which credentials: the org (tenant) and its key groups, members and invitations, client keys for your apps, join tokens for daemons, the CLI's device logins, single sign-on, org-wide settings and the signed policy each key group's venom CLI enforces. Providers, gears and routing are on Admin API: providers, gears and routing.
Calling the admin API
Every route is under /api/admin/v1 and takes Authorization: Bearer <token>, where the token is one of the
credentials in Who can use the admin API:
- the deployment's
VENOM_CLOUD_ADMIN_TOKEN(the operator): every org. Listing routes take?tenant=<org id>to narrow to one org, and writes that need an org taketenant_idin the body; - a key group admin key
vak_…: its own key group only. Org members, org-wide settings and anything marked "operator" below answer403 forbidden; - an org member's console session, which carries the member's role. The permission column below is what that role must have (Roles and permissions).
Responses are JSON with cache-control: no-store; listings are {"data": [...]}; errors use the
admin error shape (type: "mesh_error"). Every write is audited.
Example: a key for your app
Make a client key for a support bot, limited to two models and 60 requests a minute, booked to a project:
export VENOM_CLOUD=https://cloud.usevenom.dev
export ADMIN="Authorization: Bearer $VENOM_CLOUD_ADMIN_TOKEN" # or a vak_ key
TEAM=$(curl -s "$VENOM_CLOUD/api/admin/v1/teams" -H "$ADMIN" | jq -r '.data[0].id')
curl -s "$VENOM_CLOUD/api/admin/v1/keys" -H "$ADMIN" -H "Content-Type: application/json" -d "{
\"team_id\": \"$TEAM\", \"name\": \"support-bot\",
\"allowed_models\": [\"venom-fast\", \"venom-default\"], \"rpm\": 60, \"project\": \"support\"
}"const base = "https://cloud.usevenom.dev/api/admin/v1";
const headers = { Authorization: `Bearer ${process.env.VENOM_ADMIN}`, "Content-Type": "application/json" };
const { data: teams } = await (await fetch(`${base}/teams`, { headers })).json();
const res = await fetch(`${base}/keys`, {
method: "POST",
headers,
body: JSON.stringify({ team_id: teams[0].id, name: "support-bot", allowed_models: ["venom-fast"], rpm: 60 }),
});
const key = await res.json(); // key.key is the vck_ secret: store it now, it is never shown againimport os, requests
base = "https://cloud.usevenom.dev/api/admin/v1"
h = {"Authorization": f"Bearer {os.environ['VENOM_ADMIN']}"}
team = requests.get(f"{base}/teams", headers=h).json()["data"][0]["id"]
key = requests.post(f"{base}/keys", headers=h, json={"team_id": team, "name": "support-bot", "rpm": 60}).json()
print(key["prefix"], key["key"]) # the secret is in this response onlyThe answer is 201 with the key's settings, its id, tenant_id and key (the vck_ secret). A name that
already exists in the key group is 409 conflict.
Orgs and key groups
An org is a tenant; it has one or more key groups, and keys, daemons and join tokens belong to a key group. A key
group holds API keys, daemons, policies and GPU grants, not people (people are in
org teams). The API keeps the name team: team_id is the key group's id and the routes are
/api/admin/v1/teams.
| Route | Permission | What it does |
|---|---|---|
GET /api/admin/v1/tenants |
org:read |
The orgs you can see (the operator: all, or ?tenant=; anyone else: their own). |
POST /api/admin/v1/tenants |
operator | Create an org: {name, settings?}. 409 conflict on a taken name. |
PATCH /api/admin/v1/org |
org:manage |
Rename your org: {name, tenant_id?} (tenant_id for the operator). The display name only: 1 to 120 characters, trimmed, no control or invisible characters, and unique across Venom Cloud (409 conflict when taken). The id, slug, keys and join tokens stay. Answers {id, name, from, changed}; audited org.renamed. |
PATCH /api/admin/v1/tenants/{id} |
operator | {name?, settings?}. settings is merged into the stored object (keys such as retain_content, hedging, sovereign_only, platform_keys, prefer, min_daemon_version). |
POST /api/admin/v1/tenants/{id}/clerk |
operator | Link a tenant made by hand to Clerk so it can invite members: {clerk_org_id?}. Without an id Clerk creates an organisation named after the tenant; with one (org_…) that existing organisation is linked. Answers {tenant_id, clerk_org_id, slug, created, linked}; audited org.clerk_linked. 409 already_linked (the tenant has one), 409 conflict (the organisation belongs to another tenant), 409 clerk_unavailable (no Clerk here), 404 (no such organisation). |
GET /api/admin/v1/teams |
org:read |
Key groups in scope (a key group admin key: its own). |
POST /api/admin/v1/teams |
operator | {tenant_id, name, public_pool?: false}. public_pool: true lets the key group's daemons serve the public mesh. |
PATCH /api/admin/v1/teams/{id} |
operator | {name?, public_pool?}. |
DELETE /api/admin/v1/teams/{id} |
operator | Deletes a key group. 409 conflict when its keys have jobs on record: revoke the keys instead. |
GET /api/admin/v1/projects |
usage:read |
Each chargeback project: budget envelopes with spend, state and forecast, this month's and all-time spend, top members, models and costliest tasks. ?tenant= for the operator. |
Signed key group policy
Each key group has a policy the cloud signs and the venom CLI fetches with GET /v1/policy (see
Policy). Writing a section signs a new envelope with seq + 1, keeping every
other section.
| Route | Permission | What it does |
|---|---|---|
GET /api/admin/v1/teams/{id}/policy |
routing:read |
The key group's current envelope. |
PUT /api/admin/v1/teams/{id}/policy |
routing:write |
Replace the whole policy: {policy, expires_at?}. Audited policy.set. |
GET /api/admin/v1/teams/{id}/permissions |
routing:read |
The policy's permission-profile keys. |
PUT /api/admin/v1/teams/{id}/permissions |
routing:write |
Replace only the permission keys; audited policy.permissions_set. |
GET /api/admin/v1/teams/{id}/mcp |
routing:read |
The policy's mcp section (the key group's MCP registry). |
PUT /api/admin/v1/teams/{id}/mcp |
routing:write |
{allow?, servers} replaces the mcp section; audited policy.mcp_set. |
GET /api/admin/v1/policy-key |
org member, key group admin key, operator (?tenant_id=) |
The public key that signs the org's policies: the org's own key, else the deployment's. 503 policy_signing_not_configured with neither. |
POST /api/admin/v1/policy-key |
org:manage or operator |
{tenant_id?} makes the org its own signing key, sealed in the vault. 201; 409 policy_key_exists; 503 vault_unavailable without VENOM_VAULT_KEYS. |
Writing a policy with no signing key configured answers 503, like GET /api/admin/v1/policy-key.
Members and invitations
Org members exist only on deployments with Clerk sign-in (or SSO and SCIM, below). A key group admin key has no members and is refused.
| Route | Permission | What it does |
|---|---|---|
GET /api/admin/v1/members |
members:read |
The org's members (with their Venom role) and, with members:manage, pending invitations. |
POST /api/admin/v1/members/invitations |
members:manage |
{email, role, redirect_url, tenant_id?, inviter_user_id?}: a Clerk invitation that carries the Venom role. An invitation never makes an owner. |
DELETE /api/admin/v1/members/invitations/{id} |
members:manage |
Revoke a pending invitation (?tenant=, ?email= for the audit row). |
PATCH /api/admin/v1/members/{uid} |
members:manage |
{role, tenant_id?}: owner, admin, developer, billing or viewer. Only owners grant or take ownership, and an org keeps at least one owner. Answers {clerk_user_id, role, changed}. |
DELETE /api/admin/v1/members/{uid} |
members:manage |
Remove a member (?tenant=). |
Model access by role
| Route | Permission | What it does |
|---|---|---|
GET /api/admin/v1/model-access |
keys:read |
Each role's allowed_models and denied_models. |
PUT /api/admin/v1/model-access |
org:manage |
{roles: {<role>: {allowed_models, denied_models}}} replaces the roles named. Lists are exact ids or * globs; null or empty is no rule. Keys a member makes are narrowed by their role's lists. Audited model_access.updated. |
Client keys
Client keys (vck_…) call /v1. See Credentials for what a key carries.
| Route | Permission | What it does |
|---|---|---|
GET /api/admin/v1/keys |
keys:read |
Keys in scope, oldest first, with spend.today_usd, spend.month_usd and last_used_at. Never the secret or its hash. |
POST /api/admin/v1/keys |
keys:write on team_id |
Create a key (fields below). 201 with key, the secret, shown once. |
PATCH /api/admin/v1/keys/{id} |
keys:write |
Change any field below except team_id and personal. A change to models or expiry is audited key.scope, anything else key.update. 400 with nothing to change. |
DELETE /api/admin/v1/keys/{id} |
keys:write |
Revoke. Other instances stop accepting it within the key cache's lifetime (seconds). |
POST /api/admin/v1/keys/{id}/rotate |
keys:write |
A new key with the same name, scopes, limits and budget; the old one is renamed <name> (rotated <prefix>) and expires 24 hours later (sooner if it already expires sooner). Answers the new key with key and previous: {id, name, expires_at}. One rotation per key: rotate the replacement next time (409 otherwise). |
POST /api/admin/v1/keys/{id}/pause |
keys:write or billing:manage |
{reason?, anomaly_id?} (reason up to 300 characters). Every unrevoked key of the rotation chain answers 403 key_paused until resumed. Idempotent. |
POST /api/admin/v1/keys/{id}/resume |
keys:write or billing:manage |
Lift the pause. |
Key fields:
| Field | Type | Default | Meaning |
|---|---|---|---|
team_id |
uuid | required | the key group the key belongs to |
name |
string | required | unique in the key group |
allowed_models, denied_models |
string[] or null | null | exact ids or * globs; null is no rule |
rpm, tpm |
integer ≥ 0 or null | null | per-minute request and token limits |
budget |
object or null | null | {daily?: {soft_usd?, hard_usd?}, monthly?: {soft_usd?, hard_usd?}}; soft must not exceed hard |
policy |
object | {} |
{prefer?: "own" | "any" | "cloud", sovereign_only?: boolean} |
min_trust_class |
team or public |
team |
public lets the router use public daemons |
expires_at |
ISO time, epoch ms or null | null | must be in the future |
project |
string or null | null | default chargeback project when a request sends no x-venom-project |
personal |
boolean | false | the key is the signed-in member's own (their personal guardrails apply); only a member can set it, for themselves |
Key group admin keys
| Route | Permission | What it does |
|---|---|---|
GET /api/admin/v1/admin-keys |
keys:read |
Key group admin keys in scope. |
POST /api/admin/v1/admin-keys |
operator | {team_id, name}: a vak_ key, secret in this response only. |
DELETE /api/admin/v1/admin-keys/{id} |
operator | Revoke it. |
Key rotation schedule
| Route | Permission | What it does |
|---|---|---|
GET /api/admin/v1/settings/key-rotation |
providers:read (client keys: keys:read) |
The schedule and every live provider key and client key against it. |
PUT /api/admin/v1/settings/key-rotation |
providers:write for provider_days and grace_hours, keys:write for client_days |
{provider_days?: 90, grace_hours?: 24, client_days?: null, tenant_id?}: how old a key may get before it is flagged, and how long a rotated provider key keeps serving. |
Join tokens
A join token lets one or more daemons enroll into a key group (POST /api/mesh/v1/enroll, see docs/cloud-mesh.md §6).
| Route | Permission | What it does |
|---|---|---|
GET /api/admin/v1/join-tokens |
daemons:read |
Tokens in scope, newest first: prefix, labels, uses_left, expires_at. |
POST /api/admin/v1/join-tokens |
daemons:enroll on team_id |
{team_id, ttl_s?: 3600, uses?: 1, labels?}. ttl_s is 60 to 604,800 (7 days), uses 1 to 1,000. Answers {id, token, prefix, expires_at}; 403 plan_limit_reached when the plan's daemon count is used up. |
DELETE /api/admin/v1/join-tokens/{id} |
daemons:enroll |
Delete a token. Daemons already enrolled are not affected. |
CLI device logins
venom cloud login uses the device authorization grant (POST /api/cli/v1/device, then polls
POST /api/cli/v1/token). The console's /device page approves it with these routes; an app that signs its
users into venom can do the same.
| Route | Permission | What it does |
|---|---|---|
GET /api/admin/v1/device-authorizations/{user_code} |
any admin credential | The waiting login (the code shown in the terminal, XXXX-XXXX). 404 when unknown or expired (codes live 10 minutes). |
POST /api/admin/v1/device-authorizations |
keys:write on team_id to approve |
{user_code, decision: "approve" | "deny", team_id} (team_id only to approve). The CLI's next poll mints a personal vck_ key in that key group. A second decision is 409 conflict. Audited cli.login_approved / cli.login_denied. |
Single sign-on
One identity provider per org (OIDC or SAML 2.0), DNS-verified email domains, and SCIM tokens for
SCIM provisioning. Owners and admins read (sso:read); only owners change
anything (sso:manage). Writes take tenant_id in the body, deletes ?tenant=, for the operator.
| Route | What it does |
|---|---|
GET /api/admin/v1/sso |
The connection, domains, SCIM tokens (prefixes only), the URLs to give the IdP and can_manage. |
PUT /api/admin/v1/sso |
Save the connection (fields below). Saving changes the settings version, so run a test sign-in again before enabling. |
DELETE /api/admin/v1/sso |
Remove the connection; members fall back to their other sign-ins. Domains and SCIM tokens stay. |
POST /api/admin/v1/sso/enable |
{enabled}. Turning on needs a passing test sign-in of the current settings (409 sso_untested); turning off also lifts "require". |
POST /api/admin/v1/sso/require |
{required}: members must sign in through the IdP. Needs SSO enabled (409 sso_disabled) and a verified domain (409 no_verified_domain). Owners keep their other sign-in as a break-glass path. |
POST /api/admin/v1/sso/domains |
{domain}: claim an email domain. Answers the TXT record to publish. 409 too_many_domains past the limit. |
POST /api/admin/v1/sso/domains/{id}/verify |
Look up the TXT record now; the error says what is missing. |
DELETE /api/admin/v1/sso/domains/{id} |
Drop a domain. |
POST /api/admin/v1/sso/scim-tokens |
{name}: a vsc_ SCIM token, shown once. At most 5 live tokens (409 too_many_tokens). |
POST /api/admin/v1/sso/scim-tokens/{id}/rotate |
A new token in its place, shown once. |
DELETE /api/admin/v1/sso/scim-tokens/{id} |
Revoke a SCIM token. |
GET /api/admin/v1/sso/scim-groups |
The groups the IdP pushed over SCIM: members, active_members, the role a group rule gives (or null) and the org team it syncs into (or null). |
PUT /api/admin/v1/sso/scim-groups/{id}/team |
Owners. {team_id} syncs the group into that org team, {create: {name?, key?}} into a new one (named after the group by default), {team_id: null} stops. The team's people become the group's active users at once (answers synced: {added, removed}). 409 team_already_synced when another group already syncs into the team, 409 team_archived for an archived team. See Teams from your identity provider. |
Connection fields for PUT /api/admin/v1/sso:
| Field | Default | Meaning |
|---|---|---|
protocol |
required | oidc or saml |
idp |
other |
okta, google, entra or other (labels and hints only) |
default_role |
developer |
role for new members: admin, developer, billing or viewer (never owner) |
jit |
true | create members at their first sign-in |
group_roles, groups_claim |
none | group → role rules and the claim that carries groups |
deprovision_keys |
revoke |
what happens to a removed member's keys: revoke, pause or keep |
oidc_issuer, oidc_client_id, oidc_client_secret |
OIDC: the https issuer (discovery at <issuer>/.well-known/openid-configuration), client id, client secret (sealed in the vault) |
|
saml_entity_id, saml_sso_url, saml_certs, saml_metadata_url |
SAML: the IdP's entity id, https SSO URL, signing certificates, optional metadata URL |
Org settings
Each setting is a GET (read) and PUT (replace) pair; PUT bodies take tenant_id for the operator and
are audited.
| Route | Read / write permission | Body and defaults |
|---|---|---|
GET /api/admin/v1/settings/logging, PUT /api/admin/v1/settings/logging |
org:read / content:settings |
Content logging (request and response bodies, sealed): {enabled?, retention_days?}, retention 1 to 90 days. Needs VENOM_VAULT_KEYS; only the operator can turn it off (403 content_logging_enforced). |
GET /api/admin/v1/settings/platform-keys, PUT /api/admin/v1/settings/platform-keys |
providers:read / providers:write |
{enabled}: after the org's own provider keys, the cloud may use Venom's (default true). The read also says what the plan allows and which platform providers exist. |
GET /api/admin/v1/settings/pricing, PUT /api/admin/v1/settings/pricing |
providers:read / providers:write |
{mode?, custom?}: the pricing source order, provider (default: custom, then the provider's listing, then Venom's table), builtin or custom, and custom prices in $ per 1M tokens (up to 1,000). Answers the body of GET /api/admin/v1/pricing. |
GET /api/admin/v1/settings/spend-cap, PUT /api/admin/v1/settings/spend-cap |
usage:read / billing:manage or org:manage |
{monthly_usd: number | null}; the read adds month-to-date spend. Requests past the cap get 429 spend_cap_reached. |
GET /api/admin/v1/settings/secret-scanner, PUT /api/admin/v1/settings/secret-scanner |
org:read / org:manage |
{action: "redact" | "block" | "log"} for secrets found in model answers; redact by default. |
GET /api/admin/v1/settings/session-guard, PUT /api/admin/v1/settings/session-guard |
org:read / org:manage |
{max_minutes, max_usd} (1 to 10,080 minutes; $0.01 to $100,000; null clears). A session past either is paused with 429 session_paused. See Session guard. |
GET /api/admin/v1/settings/session-outcomes, PUT /api/admin/v1/settings/session-outcomes |
org:read / org:manage |
{enabled}, on by default: members' venom reports how each session ended (counts only). |
GET /api/admin/v1/settings/session-sharing, PUT /api/admin/v1/settings/session-sharing |
org:read / org:manage |
{public_links: false, retention_days: 30, public_max_days: 7}. Turning public links off ends every live link. |
GET /api/admin/v1/settings/session-summaries, PUT /api/admin/v1/settings/session-summaries |
org:read / org:manage |
{enabled: false, retention_days: 90} (1 to 730). |
GET /api/admin/v1/settings/guardrail-drafting, PUT /api/admin/v1/settings/guardrail-drafting |
org:read / org:manage |
{enabled: false, model: null, daily_limit: 20} (1 to 500 drafts per person per day): drafting guardrails from a sentence with the classifier model. |
GET /api/admin/v1/settings/injection-classifier, PUT /api/admin/v1/settings/injection-classifier |
org:read / org:manage |
{enabled: false, model: null, daily_limit: 200} (1 to 10,000 checks a day): the prompt-injection shield's classifier for borderline untrusted text. |
GET /api/admin/v1/settings/key-rotation, PUT /api/admin/v1/settings/key-rotation |
see Key rotation schedule | |
GET /api/admin/v1/settings/audit-export, PUT /api/admin/v1/settings/audit-export, DELETE /api/admin/v1/settings/audit-export |
audit:read / org:manage |
The org's S3-compatible audit-log export: {endpoint?, region, bucket, prefix?, access_key_id, secret_access_key, schedule: "hourly" | "daily" | "off", path_style?}. An empty endpoint means AWS. DELETE removes it. |
POST /api/admin/v1/settings/audit-export/run |
org:manage |
Export now, one audited run. POST /api/admin/v1/settings/audit-export/test writes a small check object first. |
See Audit export for the file format.
Your own guardrails
/me routes act for the signed-in member: they need an org member's console session and answer
403 forbidden to the admin token or a key group admin key. The rule shapes are in
Guardrails; org and key group guardrails are on
Admin API: providers, gears and routing.
| Route | What it does |
|---|---|
GET /api/admin/v1/me/guardrails |
Everything that applies to me (org, key group and my own rules), my switches and the catalog. |
POST /api/admin/v1/me/guardrails |
Add one of my own rules ({catalog} or {rule}). |
PATCH /api/admin/v1/me/guardrails/{code} |
Change one of my rules. |
DELETE /api/admin/v1/me/guardrails/{code} |
Remove one of my rules. |
PUT /api/admin/v1/me/guardrails/overrides |
{code, enabled?, action?, mode?, clear?}: my switch for an org or key group rule, as far as its lock allows (only a relaxable rule turns off). |
POST /api/admin/v1/me/guardrails/draft |
{text, gear?}: the classifier model drafts a rule from a sentence; nothing is saved. Needs guardrail drafting on; capped per person per day. |
POST /api/admin/v1/me/guardrails/{code}/suggest |
{team, note?}: offer a copy of my rule to a key group (team is its id); its admin approves or declines it. |
POST /api/admin/v1/me/guardrails/test |
{text, model?, draft?}: what my guardrails would do to pasted text. Nothing is stored. |
Onboarding paths and the palette
| Route | Permission | What it does |
|---|---|---|
GET /api/admin/v1/onboarding |
routing:read |
The org's onboarding paths, the caller's progress, the starters and (with org:manage) every member's progress. |
POST /api/admin/v1/onboarding |
org:manage |
{name, description, steps, tenant_id?}: create a path. |
PATCH /api/admin/v1/onboarding/paths/{id} |
org:manage |
{name?, description?, steps?}. |
DELETE /api/admin/v1/onboarding/paths/{id} |
org:manage |
Remove a path and its progress. |
POST /api/admin/v1/onboarding/paths/{id}/steps |
routing:read |
{step_id, done?: true}: the signed-in member ticks (or un-ticks) one of their "I mark it done" steps. |
GET /api/admin/v1/palette |
org member or operator | What the console's command palette searches in one org (names, ids and states only), each kind only if the role may read it. ?tenant= other than your own org is 403. |
Errors
| Status | code |
When |
|---|---|---|
| 400 | invalid_request |
a missing or malformed field; the message names it |
| 401 | invalid_api_key, key_expired |
a bad, revoked or expired admin credential |
| 403 | forbidden |
the role lacks the permission named in the message, the route needs the operator, or the row is in another key group or org |
| 404 | not_found |
an unknown id, or one outside your scope |
| 409 | conflict and the codes above |
a duplicate name, a second decision, an already rotated key |
| 503 | admin_not_configured, vault_not_configured, policy_signing_not_configured |
a deployment setting is missing |
Related
- Venom Cloud APIs overview: credentials, error shape, limits
- Admin API: providers, gears and routing
- Policy, Guardrails, Audit
- CLI keys