API Keys Reference

API keys are the authentication method for machine clients. For the guide, see Authentication.

Base path: /api/v1/api-keys/ Auth: JWT only — API keys cannot manage themselves.

GET /api/v1/api-keys/#

List API keys owned by or delegated to the caller.

Query parameters:

Response:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22

{
  "data": [
    {
      "id": "key_abc123",
      "name": "ci-production",
      "description": "CI pipeline key",
      "key_prefix": "sdk_live_ab",
      "status": "active",
      "permission_source": "user",
      "permission_source_id": "u_xyz",
      "scopes": ["domains:read", "records:write"],
      "rate_limit": 1000,
      "ip_whitelist": ["10.0.0.0/8"],
      "expires_at": null,
      "last_used_at": "2026-04-23T09:15:00Z",
      "last_used_ip": "10.0.1.42",
      "use_count": 1247,
      "created_at": "2026-01-10T00:00:00Z"
    }
  ],
  "total": 8
}

The secret is never returned after creation — only key_prefix (the first few characters) for identification.

POST /api/v1/api-keys/#

Create a new API key. The full secret is returned once in this response.

Request:

Response:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

{
  "id": "key_abc123",
  "name": "ci-production",
  "key": "sdk_live_f7a9c...",
  "key_prefix": "sdk_live_f7",
  "permission_source": "user",
  "permission_source_id": "u_xyz",
  "status": "active",
  "scopes": [],
  "rate_limit": null,
  "ip_whitelist": [],
  "created_at": "2026-04-23T10:00:00Z"
}

Store key in a secret manager immediately — ScaiDNS does not store it in plaintext.

GET /api/v1/api-keys/{key_id}#

Get metadata for a single key (never the secret).

PATCH /api/v1/api-keys/{key_id}#

Update metadata. Editable fields: name, description, rate_limit, ip_whitelist, expires_at.

Cannot change the permission source or the scopes after creation — create a new key if the permission model needs to change.

POST /api/v1/api-keys/{key_id}/regenerate#

Invalidate the current secret and return a new one.

Response: Same shape as create — includes the new key.

Any client using the old secret will start getting 401 immediately. Coordinate the rotation with deploy.

POST /api/v1/api-keys/{key_id}/revoke#

Temporarily disable a key without deleting it.

Request: {"reason": "suspected compromise"} (optional).

Response: Key with status: "revoked".

Revoked keys can be re-activated. Revoke is the right action when the key might come back.

POST /api/v1/api-keys/{key_id}/activate#

Re-enable a revoked key.

Response: Key with status: "active".

DELETE /api/v1/api-keys/{key_id}#

Permanently delete a key. Irreversible.

Response: 204 No Content.

GET /api/v1/api-keys/permission-sources#

List users and groups available as permission sources. Useful when building UIs for key creation.

Response:

1
2
3
4
5
6
7
8

{
  "users": [
    {"id": "u_abc", "email": "user@example.com", "name": "User Name"}
  ],
  "groups": [
    {"id": "g_abc", "name": "DNS Admins", "member_count": 3}
  ]
}

Permission sources#

Keys cannot be platform admins even if the owning user is. This is a deliberate restriction — platform-level actions require a human session.

Statuses#

Rate limiting#

If rate_limit is set, the key gets that many requests per minute. Exceeding returns 429 with a Retry-After header.

Rate limits are per-key, not per-caller. Distribute load across multiple keys if you need more throughput.

IP whitelisting#

If ip_whitelist is non-empty, requests from outside those CIDR blocks return 403. Whitelisting is evaluated against the direct source IP — be careful when running behind load balancers that rewrite source IPs.

Audit#

Every API-key-authenticated action is logged with the key ID. See Audit Log.

Error codes#

Related#

• Authentication — when to use keys vs JWTs.
• Permissions and Access — how key permissions resolve.