API keys
An API key lets a program send requests. The exchange charges each job to your workspace balance. To cap what one key can spend, set a spending limit when you issue it.
To start, issue a key.
Issue a key
- Open API keys and choose Create key.
- Enter a name and choose an access level. Choose Create key to finish, or choose Set limits to continue. More options sets an expiry and a preset.
- For a key that can spend, Set limits sets a credit limit and a profile: Cap the price, Keep prompts private or Unattended agent. Configure guardrails shows every field.
- Copy the secret. The console shows it one time only.
A key looks like sk-liquid-<key-id>-<secret>. The key id names the key on the API keys page and on every receipt.
The exchange cannot show a secret again. If you lose one, revoke the key and issue a new one.
A profile or a setting in Configure guardrails makes a guardrail for this key and links it to the key. The key follows this guardrail and the default guardrail together.
If the console cannot link the guardrail, it shows the secret with a warning. Link the guardrail from the Guardrails page.
Only workspace owners and admins can issue or revoke a key.
Choose a scope
Each key has one scope. Each scope includes the scopes below it. Give each key the lowest scope that it needs.
| Scope | Allows | Typical use |
|---|---|---|
spend |
Place jobs, and do everything below. The default. | Applications and agents |
read |
Read the receipts, balance and job decisions of this workspace, and the market. | Dashboards and reporting |
list |
Read market data only: the book, quote history and the live feed. | Monitoring |
A request outside the scope of the key returns 403 insufficient_permission.
Spending limits
A key can have a spending limit: an amount in USD and a period. Set a limit on each key that an unattended process uses.
| Period | Behaviour |
|---|---|
day, week, month |
The amount refills at the start of each period. |
| none | The amount applies to the lifetime of the key. |
When the key reaches the limit, jobs sent with the key return 402 budget_exhausted, even if the workspace balance
is higher. A key with no limit can spend the full balance. You can change the limit after you issue the key.
Send the key
Every endpoint accepts either header:
Authorization: Bearer sk-liquid-…
x-api-key: sk-liquid-…
OpenAI clients send the first. Anthropic clients send the second.
Revoke a key
Open API keys and choose Revoke on the key. The revocation starts at once, and you cannot reverse it. Jobs
awarded before the revocation continue to settlement. New requests with the key return 401 invalid_api_key.
Keep keys safe
- Issue one key for each integration. Then a revocation stops only one integration.
- Do not put a key in a browser, a mobile application or any file that you distribute.
- Keys belong to the workspace. Each member of the workspace can see them.
Reference
Expiry
You can issue a key with an expiry in days, from 1 to 3650. After the expiry, the key returns 401 invalid_api_key.
A key without an expiry is valid until you revoke it. You cannot change the expiry or the scope of an issued key.
Session keys
A key that can spend can make a session key: a key for one run of a coding agent, with the same scope, preset and addresses. POST /v1/exchange/session-keys with the key as the bearer takes a name and a ttl_seconds from 1 to 86400, and answers with the new key once. DELETE /v1/exchange/session-keys/{key_id} ends it. A session key ends when its parent expires or is revoked, cannot make another session key, and does not count toward the 100 keys of a workspace. A key with a spend limit cannot make one, because the limit counts the spend of one key. The Liquid CLI makes one for each run of an agent.
Provider keys
A provider key is a different credential. The exchange issues it to a provider, not to a workspace. It cannot spend. See Provider credentials.