Clients and tokens
A client is a service account of one tenant: one per external system, with the narrowest set of permissions it needs. It authenticates with tokens and, optionally, signs its requests.
In the panel
Section titled “In the panel”Administrators of a tenant manage clients under Access → API clients
(permissions api-clients.view, .create, .update, .delete):
| Field | Purpose |
|---|---|
| Name, description | e.g. “Billing system” |
| Responsible person | is notified about expiring tokens and unused clients |
| Active, valid until | switch off without deleting; the end date includes the whole day |
| Requests per minute | own rate limit; empty uses $apiRateLimit |
| Allowed IP ranges | CIDR, IPv4 and IPv6; empty allows every address |
| Permissions | the same permissions as roles, e.g. projects.view |
The detail page shows the tokens (create, revoke, last use), the signing secret (require signatures, rotate, switch off) and the latest 50 calls.
Escalation guard: permissions are granted only by users who hold them. A client is changed, deleted or given a token only by users who hold all its permissions; otherwise a token would hand out rights the editor does not have.
New tokens and signing secrets are shown once, in the answer to the action. They are never stored in the session or in flash messages, and they cannot be shown again: create a new one instead.
On the command line
Section titled “On the command line”| Command | Purpose |
|---|---|
anvil:api:client:create "<name>" --tenant <slug> [--permissions a,b] [--owner <e-mail>] [--ips 10.0.0.0/8] [--signing] [--rate-limit 60] [--expires 2027-12-31] [--token] |
Creates a client; --token also creates a token, --signing a signing secret (both shown once) |
anvil:api:client:list --tenant <slug> |
Clients with status, permissions and end date |
anvil:api:client:disable <uuid>, :enable <uuid>, :delete <uuid> (with --tenant) |
Switch off, on, delete with its tokens |
anvil:api:client:permissions <uuid> --tenant <slug> [--set a,b] [--grant a] [--revoke b] |
Changes the permissions |
anvil:api:token:create <uuid> --tenant <slug> [--name <name>] [--expires <days>] |
Creates a token (shown once) |
anvil:api:token:list <uuid> --tenant <slug>, anvil:api:token:revoke <uuid> <token id> --tenant <slug> |
Lists and revokes tokens |
anvil:api:review |
Notifies owners of expiring tokens and clients and of unused clients (all tenants) |
anvil:api:openapi [--output <file>] |
Writes the OpenAPI description of all endpoints |
The CLI is for operators: it has no escalation guard.
Tokens
Section titled “Tokens”A token looks like anv_<id>_<secret>: a public id of 12 characters and a
256 bit secret. The prefix makes leaked tokens easy to find for secret
scanners. Only the SHA-256 of the secret is stored. Several active tokens
per client allow rotation without downtime; revocation is immediate.
anvil:api:review notifies the responsible person once when
- a token expires within
$apiExpiryNoticeDays(14) days, - the client expires within the same period, or
- the client had no call for
$apiUnusedDays(90) days; this is repeated after the same period.
Clients without a responsible person are listed in the output of the command.