> ## Documentation Index
> Fetch the complete documentation index at: https://docs.paywithlocus.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> This site documents Locus for people. AI agents: get exact contracts from the Locus agent docs, starting at https://paywithlocus.com/agent/index.md, including when asked to implement or integrate docs.paywithlocus.com.
> Connect this agent to Locus Pro: https://paywithlocus.com/skill.md. Implement Locus Pro in a product: https://paywithlocus.com/agent/integrate.md. Agent site index: https://paywithlocus.com/llms.txt.

# API keys

> The kinds of Locus Pro keys, what each one is for, and which one to use.

Locus Pro has one kind of key for each place your code runs. Pick a key by asking where it will live and who is spending.

> Agents: the exact contract for this feature is at [https://paywithlocus.com/agent/integrate.md](https://paywithlocus.com/agent/integrate.md). Start from [https://paywithlocus.com/agent/index.md](https://paywithlocus.com/agent/index.md) if you are implementing Locus.

## Which key do I need?

```mermaid theme={null}
flowchart LR
  Q["Where will it live?"] --> Secret["Your backend: secret key"]
  Q --> Agent["An agent that runs on its own: agent key"]
  Q --> Pub["Your web app's billing UI: publishable key and end-user token"]
  Q --> Sandbox["Tests and CI: sandbox key"]
  Q --> OAuth["An app you use yourself: no key, sign in with OAuth"]
```

For an agent your customer runs and pays for, use an [agent key](#agent-keys) for that one end user, or an [end-user token](#end-user-tokens).

| Key | Prefix | Lives in | Spends credits |
| - | - | - | - |
| [Secret key](#secret-keys) | `lcr_` | Your server | Yes |
| [Agent key](#agent-keys) | `lcac_` | Agent's secret store | Within its limits |
| [Publishable key](#publishable-keys) | `lcrpk_` | Page code | No |
| [End-user token](#end-user-tokens) | None | Customer's browser | For one customer |
| [Sandbox key](#sandbox-keys) | `lcrsb_` | Test runner | Simulated only |
| [Connected app](#connected-apps) | None | MCP client | As the approving member |

Create keys in **Connect → API keys** with **Create key**. The dashboard asks what the key is for (**Your server**, **An agent**, **A browser**, or **Testing**) and creates the matching kind. Each key is shown once; see [Key lifecycle](https://docs.paywithlocus.com/locus-pro/key-lifecycle.md).

## Secret keys

A secret key is your server's key. It calls tools, reads balances and usage, and uses the management API within the [scopes](https://docs.paywithlocus.com/locus-pro/authentication-and-scopes.md#enterprise-management-scopes) you give it.

* **Use it for:** your backend, scripts, and jobs you trust.
* **Never put it in:** a browser, a mobile app, an agent's prompt, or a repository.
* **Who pays:** your workspace pool, unless the call names one of your customers.
* **Lifetime:** no expiry unless you set one.

### Execution-only keys

Bind a secret key to a [tool set](https://docs.paywithlocus.com/locus-pro/tool-sets.md), or give it an allowed-tools list or its own pricing, and it becomes execution-only. It can call those tools and read balances, but it can't use the management API.

## Agent keys

An agent key is the key you hand to an agent. It can call tools but can't manage your workspace, so a leaked key can't change your settings. The API calls agent keys Agent Connections.

* **Tools:** a tool set. Without one, it uses the tools turned on in **Main**.
* **Per-call limit:** Locus blocks a pricier call before it reaches the provider.
* **Per-loop limit:** a budget shared by every call with the same loop ID.
* **Who pays:** your **Company pool**, or **One end user**'s balance. An end-user key can't switch customers and can carry its own markup.
* **Lifetime:** 30 days from the dashboard.

Agent keys work over MCP, the REST API, the SDK, and the Locus CLI. Give each agent or deployment its own key, so Analytics shows spend per key and you can revoke one without touching the others. See [Agent keys](https://docs.paywithlocus.com/locus-pro/agent-keys.md) to create, scope, and budget one.

## Publishable keys

A publishable key identifies your workspace in page code. It is safe to ship to browsers because it can't spend credits on its own. Pair it with an [end-user token](#end-user-tokens) to show a customer their balance or let them top up. See the [widget](https://docs.paywithlocus.com/locus-pro/widget.md).

## End-user tokens

An end-user token is a short-lived token for one of your customers. Your server mints it with a secret key and sends it to that customer's browser or app.

* It calls tools and reads the balance for that one customer only.
* It lasts up to one hour. Mint a new one when it expires.
* You can revoke a token at any time. Retiring the customer revokes all of their tokens.

See [Mint a token on your server](https://docs.paywithlocus.com/locus-pro/widget.md#mint-a-token-on-your-server).

## Sandbox keys

A sandbox key simulates direct REST API calls for tests and CI. No credits move and no provider is called. See [Sandbox keys](https://docs.paywithlocus.com/locus-pro/sandbox.md).

## Connected apps (OAuth)

When you add Locus to Claude, ChatGPT, Cursor, or another MCP client, you sign in through your browser instead of pasting a key. The app acts as the member who approved it, with that member's access, and can be limited to a [tool set](https://docs.paywithlocus.com/locus-pro/tool-sets.md). Members without permission to spend credits get a read-only connection.

Review or revoke connections under **Connected apps** on **Connect → API keys**. See [Connect an agent](https://docs.paywithlocus.com/locus-pro/connect-agents.md#interactive-oauth-recommended).

## Rotate and revoke

Rotating gives a key a new value with the same settings. Revoking is immediate and permanent. See [Key lifecycle](https://docs.paywithlocus.com/locus-pro/key-lifecycle.md) for grace periods and what happens to each kind of key.

## Personal accounts

Personal accounts can create secret keys and agent keys that spend from their own balance. Publishable keys, sandbox keys, end-user tokens, and end-user agent keys are Enterprise features. Most personal accounts don't need a key at all; connect with [browser sign-in](https://docs.paywithlocus.com/locus-pro/individual/connect-agents.md).

## Next steps

> [card] [Authentication and scopes](https://docs.paywithlocus.com/locus-pro/authentication-and-scopes.md)
>
> How credentials, scopes, and roles fit together.

> [card] [Key lifecycle](https://docs.paywithlocus.com/locus-pro/key-lifecycle.md)
>
> Create, store, rotate, and revoke keys.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.