Clients & keys
Create, list, update and delete clients, and issue keys on them.
Base path /api/v1/client. Every route takes project_env as a query parameter.
See Clients & templates for the concepts.
List clients
GET /api/v1/client?project_env=payments-api-production| Query | Notes |
|---|---|
project_env | Required |
page, limit | 1-based; limit 1–100, default 10 |
name | Filter by name |
type | person · company · service · device · internal |
templateId | Filter by template |
Create clients
POST /api/v1/client?project_env=payments-api-production{
"name": "Acme mobile app",
"type": "company",
"templateId": "tpl_partner",
"ipWhitelist": ["203.0.113.0/24"],
"metadata": { "accountId": "acct_912" },
"keys": [
{ "name": "default", "expiresAt": "2027-01-01T00:00:00Z" }
]
}Pass an array instead to create up to 100 clients in one call.
The response contains the raw keys once. The database stores only a SHA-256 hash and a 12-character display prefix. Store them now.
| Field | Notes |
|---|---|
name | Required. Up to 100 characters, no control characters |
type | Required |
templateId | Must be a template in the same environment, or 404 |
ipWhitelist | Up to 100 addresses or CIDR blocks, IPv4 or IPv6 |
metadata | Up to 8 KiB, 5 levels deep |
keys | Up to 10 per request |
Get a client
GET /api/v1/client/{client_uuid}?project_env=…Returns the client with its keys. Key records carry the display prefix and status — never the raw key.
Update a client
PUT /api/v1/client/{client_uuid}?project_env=…{
"name": "Acme mobile app (v2)",
"ipWhitelist": ["203.0.113.0/24", "198.51.100.7"],
"keys": [
{ "name": "rotated-2026" },
{ "id": "k_2f9c…", "name": "old", "expiresAt": "2026-10-01T00:00:00Z" }
]
}A keys entry without an id issues a new key; with an id it updates
that one.
What can change on an existing key:
| Name, metadata | Freely |
| Expiry | Shortened only |
| Secret, scopes, environment | Never — they are signed. Issue a new key |
Disabling a client makes every key it holds fail at
check 5 with 403.
Delete a client
DELETE /api/v1/client/{client_uuid}?project_env=…Removes the client and its keys. Immediate in server mode.
List templates
GET /api/v1/client/templates?project_env=payments-api-productionReturns the rate-limit templates available in this environment, with their hour, day, week and month limits.
Validate a key
POST /api/v1/client/{client_uuid}?project_env=…&method_path=…Documented separately — see Validating a key.