Admin keys

An admin key manages a workspace from your own code. It creates and limits the inference keys your customers or devices use, and reads usage, logs and settings. It cannot call a model.

Create an admin key

1. In the console, open API keys › Admin keys and choose Create admin key. Admins and the workspace owner can create one.
2. Choose who the key belongs to and which scopes it holds.
3. Copy the key. It starts with sk-syn-admin- and is shown once.

Scopes

A scope opens one part of the management API. A write scope includes its read scope. A request the key has no scope for returns 403 insufficient_scope.

Who a key belongs to

• You. The key is disabled if you leave the workspace. If you stay but are no longer an admin, requests return 403 key_creator_not_authorized.
• The workspace. The key keeps working after its creator leaves or changes role. Use it for CI and integrations. When its creator leaves, the key passes to the workspace owner together with the inference keys it created, and they all keep working.

You choose this when you create the key. It cannot be changed later.

Authentication

Send the key as a Bearer token. An admin key works on the management API only: the model endpoints under /v1/ refuse it, and the management API refuses an inference key (sk-syn-) with 401 wrong_key_kind.

Authorization: Bearer sk-syn-admin-...

Create an inference key

POST /api/v1/keys

curl https://synthorai.io/api/v1/keys \
  -H "Authorization: Bearer sk-syn-admin-..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: device-abc-123" \
  -d '{
    "name": "Device abc-123",
    "limit_usd": 5.0,
    "limit_reset": "monthly",
    "allowed_models": ["claude-haiku-4-5"],
    "metadata": { "tenant_id": "acme", "device_id": "abc-123" }
  }'

import requests

resp = requests.post(
    "https://synthorai.io/api/v1/keys",
    headers={
        "Authorization": "Bearer sk-syn-admin-...",
        "Idempotency-Key": "device-abc-123",
    },
    json={
        "name": "Device abc-123",
        "limit_usd": 5.0,
        "limit_reset": "monthly",
        "allowed_models": ["claude-haiku-4-5"],
        "metadata": {"tenant_id": "acme", "device_id": "abc-123"},
    },
)
inference_key = resp.json()["data"]["key"]  # full key - shown only once

The response includes the full key as key, once. Store it now: later reads return only key_prefix.

{
  "data": {
    "id": 42,
    "key": "sk-syn-d4f0...e91b",
    "key_prefix": "sk-syn-d4f0...",
    "name": "Device abc-123",
    "enabled": true,
    "status": "enabled",
    "limit_usd": 5.0,
    "used_usd": 0,
    "limit_reset": "monthly",
    "allowed_models": ["claude-haiku-4-5"],
    "ip_allowlist": [],
    "expires_at": null,
    "include_byok_in_limit": true,
    "rate_limit": { "rpm": 0, "tpm": 0 },
    "metadata": { "tenant_id": "acme", "device_id": "abc-123" },
    "created_via": "provisioning_api",
    "created_at": "2026-10-01T12:00:00Z"
  },
  "meta": { "request_id": "01a1..." }
}

To retry a create safely, send an Idempotency-Key header. A repeat with the same value returns the first response, without the secret. The key holds that response for 24 hours, even if the resource was deleted since: to create it again, use a new key.

List and filter keys

GET /api/v1/keys

Filter by any metadata field with ?metadata.<name>=<value>. Results come in pages: pass meta.next_cursor as cursor for the next one.

# all keys
curl https://synthorai.io/api/v1/keys \
  -H "Authorization: Bearer sk-syn-admin-..."

# only keys tagged tenant_id=acme, 50 at a time
curl "https://synthorai.io/api/v1/keys?metadata.tenant_id=acme&limit=50" \
  -H "Authorization: Bearer sk-syn-admin-..."

Read, change, rotate and delete

• GET /api/v1/keys/{id} returns one key.
• PATCH /api/v1/keys/{id} changes only the fields you send. "enabled": false stops the key without deleting it.
• POST /api/v1/keys/{id}/rotate gives the key a new secret. The old one stops working at once.
• DELETE /api/v1/keys/{id} deletes the key. Requests that use it return 401 at once.

# stop a key without deleting it
curl -X PATCH https://synthorai.io/api/v1/keys/42 \
  -H "Authorization: Bearer sk-syn-admin-..." \
  -H "Content-Type: application/json" \
  -d '{ "enabled": false }'

# give it a new secret
curl -X POST https://synthorai.io/api/v1/keys/42/rotate \
  -H "Authorization: Bearer sk-syn-admin-..."

# delete it
curl -X DELETE https://synthorai.io/api/v1/keys/42 \
  -H "Authorization: Bearer sk-syn-admin-..."

An admin key acts for one member: whoever created it, or the workspace owner once the creator of a workspace key has left. It can change, rotate and delete only that member’s keys, including the ones it created; another member’s key returns 403 not_key_creator, even with the owner’s admin key. On a dedicated instance, any admin key of the workspace can manage every member’s key, as admins can in the console. A key an admin disabled can only be enabled again by an admin: anyone else gets 403 disabled_by_admin.

Limits and spend

limit_usd is what the key may spend and used_usd is what it has spent. At the limit, status becomes limit_reached and requests are refused until you raise the limit or the period resets.

Sizing per-key spend limits? The LLM API cost calculator turns a customer’s expected token volume into a monthly figure you can set as limit_usd.

Errors

Errors use the management API’s envelope: error.code names the reason and error.message says what to do. On /api/provisioning/keys the same code comes as error.type. These codes are specific to admin keys and the keys API:

Provisioning keys and /api/provisioning

Keys issued before admin keys (sk-syn-prov-) keep working, with the keys.read and keys.write scopes. The earlier path /api/provisioning/keys is still served with its own field names (quota, status). Use /api/v1/keys for new integrations.

The management API also covers billing, the request log, prompts and workspace settings. See the API overview and the OpenAPI document.