Skip to main content
The admin API is the management plane: everything a script can do to your organization without a person signing in. It takes a mak_ admin key — see Admin Keys for minting, scopes, rotation, and expiry.
Every route below accepts an admin key carrying the permission named beside it. A permission you were not granted is a 403, whatever the route.
Only six routes on this page appear in the API Reference tab: POST /v1/usage, POST /v1/usage/events, POST /v1/usage/rejections, GET /v1/usage/events/{event_id}/attempts, GET /v1/usage/rate-limits and GET /v1/usage/spend-trend. Everything else here — keys, org, members, billing, alerts, webhook deliveries, routing-policy templates, provider keys, analytics, logs, the CSV export and the two org spend routes — is withheld from the published spec, so this page is its reference.

Scope, in one line

Each route also has a minimum scope — the narrowest key that reaches it. A self-scoped key reaches only rows it owns; org reaches the whole organization. Eight permissions act on the organization itself and can therefore only be granted at org scope: org:read, org:write, alerts:read, alerts:write, limits:read, limits:write, logs:read, logs:read_bodies. Asking for them at self or team is a 422 at mint time. Of the rest, only keys:read, keys:write and provider_keys:read do anything below org scope. members:write, billing:read and usage:read can be granted narrower, but every route that reads them requires org — so a self-scoped key carrying one gets a 403 rather than a narrower answer. Grant those at org or not at all.

API keys

Manage the rsk_ inference keys your applications call models with. A key minted by an admin key belongs to that key’s lineage, not to a person, and survives rotation of the admin key that created it. See Admin Keys for what that means for ownership and billing.

Organization

org:write stops at the three org-wide privacy controls. PATCH /v1/orgs/current refuses zero_data_retention, default_pii_policy and default_body_log_policy to an admin key with a 403, before it validates anything else in the body. Turning zero data retention off starts storing prompt bodies again and that disclosure cannot be taken back, so it stays a signed-in action. Change them in the dashboard.

Members and invitations

Sending a new invitation is a dashboard action. POST /v1/orgs/current/members authenticates a signed-in person, so an admin key can revoke, resend and list invitations but cannot create the first one. Roles, teams and ownership transfer are dashboard-only for the same reason.

Usage

Seven of these also accept an rsk_ key carrying the usage:read scope. Three do not — the CSV export and the two org spend routes take an admin key or a dashboard session, and an rsk_ bearer gets a 401. They are marked below.
GET /v1/usage/requests/{request_id} — the single-request lookup — is the one usage route an admin key does not reach. It takes an rsk_ key with the usage:read scope. Usage API covers the request and response shapes for this group.

Analytics

The analytics surface reads the same traffic as the usage group, pre-aggregated. The same usage:read permission at org scope opens it, and an admin key reads the whole organization’s traffic here — unlike an rsk_ key, which sees only its own rows.
Reads only. Creating, updating and deleting a saved view is refused to any key, admin key included — saved views are managed from a dashboard session.Analytics is rolled out per environment. Analytics API documents the dimensions, measures and query shapes.

Billing

Reading invoices is the whole of billing an admin key reaches. Paying is not — topping up, checkout and auto-recharge setup all require a signed-in person, and the permission that authorizes spending (billing:pay) cannot be granted to an admin key at all. A leaked admin key cannot spend your balance.

Alerts and notifications

Alert channels, the policies that fire into them, and the outbound webhook delivery log. See Notifications for the event catalogue and payload shapes.
These paths are /alerts/..., not /v1/alerts/....
Rotating a channel’s signing secret keeps the previous one verifying for a grace window, so a receiver can cut over without dropping deliveries.

Webhook deliveries

Routing policy templates

Shared retry and fallback policy that keys reference instead of each carrying their own. See Retry and fallback.
Creating a template is a dashboard action. An admin key can read and edit templates but cannot create the first one.

Provider keys

This is a read of the catalogue, not of your credentials. Adding, listing or removing your own BYOK keys is a dashboard action — see Bring your own key.

Logs

A Loki-compatible read of your organization’s own log tenant, so you can point your Grafana at Mesh directly. logs:read covers the query surface; logs:read_bodies additionally serves stored request and response bodies. Setup, fields, queries and limits: Request Logs.
logs:read_bodies is held by the owner and admin roles only: no custom role carries it, so a key carrying it was minted by an owner or an admin. Bodies are never served for an organization under zero data retention.
Reads are capped per organization per minute. Records older than 7 days are not returned.

What an admin key never reaches

Errors

API errors covers the error envelope.
  • Admin Keys — minting, permissions, scope, rotation, revocation
  • Authentication — rsk_ against mak_
  • API Keys — the inference keys this API manages
  • Usage API — request and response shapes for the usage group
  • Notifications — the event catalogue behind alerts and webhooks