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.

✕

Scopes are required

A key must say what it may do. name and scopes are both required, and scopes must contain at least one permission.

There is no "full access" key. An empty array is rejected, not interpreted as unrestricted.

Code
curl -X POST https://api.kontier.eu/v1/api-keys \
  -H "Authorization: Bearer sk_live_…" \
  -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. 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/rotate) issues a replacement while the old key keeps working, so you can deploy the new one before retiring the old. 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