API Keys

Manage API keys for your account. All endpoints require authentication.

Create an API key

POST /v1/api-keys

Creates a new API key. If permissions is omitted, creates a root key (requires root key authentication). If permissions is provided, creates a restricted key. Keys can only create keys with equal or lesser permissions (no privilege escalation).

The plaintext key is returned only on creation and cannot be retrieved again.

Request body

Field	Type	Required	Description
environment	string	Yes	test or live
name	string	No	Human-readable label
permissions	object	No	Map of resource name to permission level (None, Read, Write). Omit for root key.

Valid resources: transactions, locations, webhooks, api_keys, account, tokens.

Example

curl -X POST https://api.zyntem.dev/v1/api-keys \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer zyn_test_abc123def456..." \
  -d '{
    "environment": "test",
    "name": "POS read-only",
    "permissions": {
      "transactions": "Read",
      "locations": "Read"
    }
  }'

Response 201 Created

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "key": "zyn_test_abc123def456ghi789...",
  "key_prefix": "zyn_test_",
  "environment": "test",
  "name": "POS read-only",
  "key_type": "restricted",
  "permissions": {
    "transactions": "Read",
    "locations": "Read"
  },
  "created_at": "2026-03-20T10:00:00Z"
}

Errors

Status	Error	Cause
400	environment must be 'test' or 'live'	Invalid environment
400	unknown permission resource: ...	Invalid resource in permissions map
403	only root keys can create new root keys	Restricted key tried to create a root key
403	privilege escalation: ...	Key tried to grant higher permissions than it has

---

List API keys

GET /v1/api-keys

Lists all API keys for the authenticated account. Key hashes are never returned.

Example

curl https://api.zyntem.dev/v1/api-keys \
  -H "Authorization: Bearer zyn_test_abc123def456..."

Response 200 OK

[
  {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "key_prefix": "zyn_test_",
    "environment": "test",
    "name": "POS read-only",
    "key_type": "restricted",
    "permissions": { "transactions": "Read", "locations": "Read" },
    "created_at": "2026-03-20T10:00:00Z",
    "last_used_at": "2026-03-21T14:30:00Z",
    "revoked": false
  }
]

---

Revoke an API key

DELETE /v1/api-keys/{id}

Revokes an API key immediately. Cannot revoke the key used for the current request.

Example

curl -X DELETE https://api.zyntem.dev/v1/api-keys/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer zyn_test_abc123def456..."

Response 204 No Content

Errors

Status	Error	Cause
400	cannot revoke the API key used for this request	Self-revocation
404	API key not found or already revoked	Invalid ID or already revoked

---

Rotate an API key

POST /v1/api-keys/{id}/rotate

Revokes the specified key and creates a new one with the same environment. Returns the new plaintext key once. Cannot rotate the key used for the current request.

Example

curl -X POST https://api.zyntem.dev/v1/api-keys/a1b2c3d4-e5f6-7890-abcd-ef1234567890/rotate \
  -H "Authorization: Bearer zyn_test_other_key..."

Response 200 OK

{
  "new_key": {
    "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "key": "zyn_test_newkey123...",
    "key_prefix": "zyn_test_",
    "environment": "test",
    "key_type": "root",
    "created_at": "2026-03-21T10:00:00Z"
  },
  "revoked_key_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Errors

Status	Error	Cause
400	cannot rotate the API key used for this request	Self-rotation
404	API key not found or already revoked	Invalid ID or already revoked