---
title: "Admin API: orgs, members and keys"
description: 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.
section: cloud
order: 300
audience: [builder, operator, agent]
sources: [services/nodejs-cloud/app/api/admin/v1, services/nodejs-cloud/lib/models/admin.ts, services/nodejs-cloud/lib/orgs/admin.ts, services/nodejs-cloud/lib/sso/settings.ts, services/nodejs-cloud/lib/cli-login/index.ts, services/nodejs-cloud/lib/policy/index.ts, services/nodejs-cloud/lib/guardrails/member.ts, services/nodejs-cloud/lib/onboarding, docs/cloud-mesh.md]
features: [cloud.api-admin-me, cloud.api-admin-members, cloud.api-admin-teams, cloud.api-admin-projects, cloud.api-admin-keys, cloud.api-admin-admin-keys, cloud.api-admin-join-tokens, cloud.api-admin-device-authorizations, cloud.api-admin-sso, cloud.api-admin-settings, cloud.api-admin-policy-key, cloud.api-admin-model-access, cloud.api-admin-onboarding, cloud.api-admin-palette, cloud.api-admin-tenants, cloud.api-admin-org]
---

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](/docs/cloud/api-admin-routing.md).

## Calling the admin API {#calling}

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](/docs/cloud/api-overview.md#admin-credentials):

- 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](/docs/cloud/api-overview.md#roles)).

Responses are JSON with `cache-control: no-store`; listings are `{"data": [...]}`; errors use the
[admin error shape](/docs/cloud/api-overview.md#errors) (`type: "mesh_error"`). Every write is audited.

### Example: a key for your app {#example}

Make a client key for a support bot, limited to two models and 60 requests a minute, booked to a project:

```bash
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\"
}"
```

```ts
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
```

```python
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 {#orgs}

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](/docs/cloud/teams.md)). 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 {#policy}

Each key group has a policy the cloud signs and the venom CLI fetches with `GET /v1/policy` (see
[Policy](/docs/security/policy.md#signed)). 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 {#members}

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 {#model-access}

| 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 {#keys}

Client keys (`vck_…`) call `/v1`. See [Credentials](/docs/cloud/api-overview.md#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 {#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 {#key-rotation}

| 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 {#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 {#device}

`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 {#sso}

One identity provider per org (OIDC or SAML 2.0), DNS-verified email domains, and SCIM tokens for
[SCIM provisioning](/docs/cloud/api-overview.md#credentials). 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](/docs/cloud/teams.md#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 {#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](/docs/cloud/api-admin-routing.md#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](/docs/security/session-guard.md#cloud). |
| `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](#key-rotation) | |
| `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](/docs/security/audit.md#export) for the file format.

## Your own guardrails {#me}

`/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](/docs/security/guardrails.md#kinds); org and key group guardrails are on
[Admin API: providers, gears and routing](/docs/cloud/api-admin-routing.md#guardrails).

| 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 {#onboarding}

| 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 {#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 {#related}

- [Venom Cloud APIs overview](/docs/cloud/api-overview.md): credentials, error shape, limits
- [Admin API: providers, gears and routing](/docs/cloud/api-admin-routing.md)
- [Policy](/docs/security/policy.md), [Guardrails](/docs/security/guardrails.md), [Audit](/docs/security/audit.md)
- [CLI keys](/docs/cli/keys.md)
