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 themconfig.write, and to list every user's keysapi_keys.read. The built-in Platform Operator role can view, and Settings Manager addsconfig.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
| Field | What to enter |
|---|---|
| Key name | A label you will recognise later, at least two characters. |
| Environment | Production, 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 date | Optional. The key stops working once this date starts (UTC). |
| Allowed origins/IPs | Optional, one per line. See the warning below. |
| Scopes | Run 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"400withtaskId is required.: the key works.401invalid_api_key: the key is wrong, revoked or expired, or its allowed origins reject the request.403insufficient_scope: the key lacks Read AI task status.429rate_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.