API keys

An API key authenticates your system to Kontier. You pass it as a bearer token, and every request resolves to the organization the key belongs to, which is why no request carries an organization parameter.

✕

Access is required

A key must say what it may do. name is required, and so is exactly one of access_preset and scopes:

• access_preset is a named grant expanded against the permissions you hold: READ_ONLY (every read permission you hold, the least-privilege choice) or FULL_ACCESS (everything you hold). A key never carries more than its creator.
• scopes lists explicit permissions, each one you must hold yourself. GET /v1/permissions returns the catalog. An empty list is not interpreted as unrestricted.

Code
curl -X POST https://api.kontier.eu/v1/api-keys \
  -H "Authorization: Bearer sk_live_…" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "name":   "Billing sync",
    "scopes": ["customer.read", "subscription.read", "invoice.read"]
  }'

Give a key the permissions its job needs and no more. A read-only reporting integration should not hold a scope that can cancel a subscription.

Live and test keys

key_type is sk_live or sk_test. Omit it: the workspace you create the key in decides (a sandbox mints sk_test, a live workspace sk_live), and a value that disagrees with the workspace is refused. A test key operates against the sandbox workspace and cannot touch live data. The prefix on the key makes which is which visible at a glance, including in a log line where it should not have been.

Narrowing a key further

Two optional restrictions, both worth using for machine-to-machine keys:

• allowed_ips limits where the key may be presented from, as addresses or CIDR blocks. A key that leaks is useless from anywhere else.
• expires_at makes the key stop working on a date. Omit it and the key lives until revoked.

Rotation and revocation

Rotate (POST /v1/api-keys/{id}/rotate) issues a replacement for one key, with the same name, scopes, IP allow-list and expiry, and puts the replaced key on a 24-hour grace expiry. Both work during that window, so you can deploy the new one before the replaced one stops. The answer is the new key as every read shows it, with its replaces_id naming the rotated key, plus the key itself in key, returned once, as on create. The rotated key's expires_at says when it stops. A key already expiring within the grace window cannot be rotated (409). This is the routine path, and it should be routine.

Revoke (POST /v1/api-keys/{id}/revoke) stops a key immediately. This is the path for a key you believe is compromised, and it will break anything still using it, which is the point.

Reference