# 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).

## Issue a key

1. Open **API keys** and choose **Create key**.
2. 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.
3. 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.
4. 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](https://inference.ai.exchange/docs/guardrails.md) 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](https://inference.ai.exchange/docs/cli.md) 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](https://inference.ai.exchange/docs/provider.md).

## Next steps

- [Quickstart](https://inference.ai.exchange/docs/quickstart.md)
- [Guardrails](https://inference.ai.exchange/docs/guardrails.md)
- [Purchasing rules](https://inference.ai.exchange/docs/rules.md)