Kernlift

Issue API keys and set rate limits

Users call the AI and upload endpoints from scripts with scoped keys, and you control how often each key may call them.

API keys let a user call selected /api/* endpoints without a browser session. Any signed-in user can create keys for their own account. Operators set the limits. Keys need no provider and no environment variables.

Before you begin

  • A signed-in user account to create the key.
  • To view limits you need config.read, to change them config.write, and to list every user's keys api_keys.read. The built-in Platform Operator role can view, and Settings Manager adds config.write.
  • For AI calls, a routed scene. See Route scenes and set pricing.

Create a key

Open the form

Sign in, open API Keys in the app sidebar (/app/api-keys) and click Create API Key.

Fill in the fields

FieldWhat to enter
Key nameA label you will recognise later, at least two characters.
EnvironmentProduction, Staging or Development. A label only; it does not change what the key can do.
Rate limit (req/sec)Requests allowed per window on endpoints without an API rule. Defaults to 100.
Expiry dateOptional. The key stops working once this date starts (UTC).
Allowed origins/IPsOptional, one per line. See the warning below.
ScopesRun AI tasks, Read AI task status, Upload files. The first two are selected by default.

Copy the secret

Click Create key, then Copy the Secret key. It is shown once and cannot be retrieved later. If it is lost, create a new key.

Scopes cannot be changed after creation.

Allowed origins block server-to-server calls

When Allowed origins/IPs is filled, a request is accepted only if its Origin header matches a line exactly, scheme and port included. IP addresses are not matched, and requests without an Origin header, such as curl or server code, are rejected. Leave it blank for server-to-server keys.

Call the API with the key

Send the key as Authorization: Bearer <key> or x-api-key: <key>.

curl -X POST "https://your-domain.example/api/$SCENE/generate" \
  -H "Authorization: Bearer $KERNLIFT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Summarise this changelog"}'

curl "https://your-domain.example/api/status?taskId='taskId'" \
  -H "x-api-key: $KERNLIFT_API_KEY"

$SCENE is a scene code from Scene routing. The first call needs Run AI tasks, the second Read AI task status, and POST /api/assets/upload needs Upload files. Calls run as the key's owner and spend the owner's credits. GET /api/openapi.json serves an OpenAPI 3.1 document for these endpoints.

Set rate limits for all keys

Open Rate Limits

In the admin console, go to Platform → Rate Limits (/admin/rate-limits).

Choose the backend

Rate limit backend: Memory counts requests inside each server process. Choose Redis when several instances serve the API, and enter Redis URL (for example redis://default:password@host:6379). If Redis cannot be reached, the request is counted in memory. Switching back to Memory clears the saved URL.

Set the defaults

Default limit (req/sec) and Default window (sec) apply to any endpoint without its own rule. Limits range from 1 to 10,000 and windows from 1 to 3,600 seconds.

Set the API rules

API rules has one row each for AI generate (/api/{scene}/generate), AI status (/api/status) and Asset upload (/api/assets/upload). Set Limit (req) and Window (sec) per row, then click Save configuration.

API rules apply to every key on those three endpoints and take precedence over the limit a user picks when creating a key. That per-key limit applies to the other key-authenticated endpoints.

Give one key different limits

Find the key

Go to Platform → API Keys (/admin/api-keys). Key inventory lists every user's keys, masked, with owner, status, expiry, Last used and usage event count. Filter with Search and Status, then click Apply.

Edit its rules

Click API rules on the row. API key default sets the key's own limit and window. Each endpoint row shows the value it currently inherits and lets you set a Rate limit and Window for this key alone.

Save

Click Save. Every row in the dialog is stored for that key, so later changes on Rate Limits no longer reach it.

Revoke a key

On /app/api-keys, click Revoke on the key's row, type the key name and click Confirm revoke. Requests with that key fail immediately. Operators cannot create or revoke a user's key, but a banned user's keys stop working until the ban is lifted.

Verify

Call the status endpoint without a taskId:

curl -i "https://your-domain.example/api/status" \
  -H "Authorization: Bearer $KERNLIFT_API_KEY"
  • 400 with taskId is required.: the key works.
  • 401 invalid_api_key: the key is wrong, revoked or expired, or its allowed origins reject the request.
  • 403 insufficient_scope: the key lacks Read AI task status.
  • 429 rate_limited: a limit was hit. Wait for the window to pass.

Each attempt appears as accepted or rejected on Usage stats (/app/api-keys/usage). pnpm validate:api-keys checks the key inventory, scopes and the verification limit.

Troubleshooting

A request returns insufficient_scope

The key lacks the scope the endpoint requires. For example, a key with only the default scopes cannot call POST /api/assets/upload. Keys cannot be edited, so create a new key with the needed scope.

Limits reset or differ between servers

The Memory backend keeps counters in each server process. On Rate Limits, set Rate limit backend to Redis and fill in Redis URL so all instances share counters.

A route ignores the key and asks for a session

Some endpoints accept sessions only: /api/chat, /api/chat/conversations and /api/billing/checkout.

Many rate_limited responses from one IP

Independently of the limits above, key verification is capped at 120 attempts per 60 seconds for each key prefix and client IP, which slows down guessing. Spread the calls out or stop sending invalid keys.

Reference

Next steps