Skip to content
Docs menu

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.

View .md

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 take tenant_id in the body;
  • a key group admin key vak_…: its own key group only. Org members, org-wide settings and anything marked "operator" below answer 403 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 again
import 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 only

The 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