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

# Agent keys

> Give an unattended agent its own scoped key, with only the tools, budget, and lifetime you choose.

An agent key (`lcac_…`) lets one agent runtime call Locus tools within limits you set. Use it for hosted agents and background services that run without you. The API and SDK call it an Agent Connection.

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

## How it works

You create the key from the dashboard or your backend, and decide what it may do. The agent uses only that key. On every call, Locus checks the key's tools and budget before anything runs or is charged.

```mermaid theme={null}
flowchart TD
  S["Dashboard or your backend"] -->|"creates"| K["Agent key"]
  C["Tools, limits, expiry, account"] -.- K
  K --> R["Agent runtime"]
  R -->|"each call"| L["Locus checks scope and budget"]
  L --> X["Paid tool"]
```

* An agent key can call tools. It can't manage your workspace settings or keys.
* It spends from your pooled balance, or from one customer's balance.
* If you use the agent yourself in a client with browser sign-in, [OAuth](https://docs.paywithlocus.com/locus-pro/connect-mcp-clients.md) is simpler.

> [!WARNING]
>
> Keep your `lcr_…` secret key on your server. Give the agent a scoped
> `lcac_…` agent key. Store keys in a secret manager, never in source control.

## Create an agent key

To create a key, dashboard users must be an owner or admin and complete recent MFA or passkey verification. A server key needs both `credentials:manage` and `credits:move`.

> [tab] Dashboard
>
> **1. Start a new key**
>
> Open **Connect → API keys**, select **Create key**, and choose **An agent**.
>
> **2. Choose what it can do**
>
> Pick a tool set, the account it spends from, its spending limits, and
> when it expires. **One end user** lets you pick an existing end-user ID
> or type a new one.
>
> **3. Save it securely**
>
> Locus shows the key and a ready-to-use MCP configuration. Store the key
> right away; it is shown only on creation and rotation.

> [tab] From your backend
>
> List the exact `provider/endpoint` slugs the agent needs:
>
> ```bash title="Create an agent key" theme={null}
> curl --fail-with-body -X POST "https://api.paywithlocus.com/api/credits/agent-connections" \
>   -H "Authorization: Bearer $LOCUS_SECRET_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "name": "research-agent-prod",
>     "mode": "platform",
>     "tools": { "enable": ["tavily/search", "firecrawl/scrape"] },
>     "maxCreditsPerCall": "250",
>     "expiresInSeconds": 2592000
>   }'
> ```
>
> Listing a tool your workspace has not enabled turns it on, which also
> needs `catalog:write`. Locus refuses a slug its catalog does not know.
> Store the returned key right away.

### What you choose

| Setting | What you choose |
| - | - |
| Account | Your pooled balance, or one customer's balance |
| Tools | Exact tools, or a tool set |
| Per-call limit | The largest charge one call may incur, in credits |
| Per-run limit | A shared credit budget for every call in one run |
| Expiry | 5 minutes to 365 days; 30 days by default |

End-user agent keys can also carry their own pricing overrides.

> [!WARNING]
>
> Leaving out the tool list allows every tool your workspace has enabled. An
> empty list allows none. Creating a key never turns on custom APIs or the
> always-on Recipe routes; they keep their own settings.

### What you can change later

The account is fixed when you create the key. The tool list can grow in two ways: approve a tool access request the agent sends, which adds that tool to the key, or move the key onto another tool set through the API. To change anything else, create a replacement key.

## Agent key configuration

Set `LOCUS_AGENT_CONNECTION` to the saved `lcac_…` key, then add it to your client as a bearer token.

> [tab] Codex
>
> Add to `~/.codex/config.toml`:
>
> ```toml title="~/.codex/config.toml" theme={null}
> [mcp_servers.locus_pro]
> url = "https://api.paywithlocus.com/api/credits/mcp"
> bearer_token_env_var = "LOCUS_AGENT_CONNECTION"
> ```

> [tab] Claude Code
>
> ```bash theme={null}
> : "${LOCUS_AGENT_CONNECTION:?Set LOCUS_AGENT_CONNECTION first}"
> claude mcp add --transport http locus-pro \
>   https://api.paywithlocus.com/api/credits/mcp \
>   --header "Authorization: Bearer $LOCUS_AGENT_CONNECTION"
> ```
>
> Run `/mcp` to connect. Remove an existing `locus-pro` entry before replacing it.

> [tab] Cursor
>
> Add to `.cursor/mcp.json` and keep this file out of source control:
>
> ```json title=".cursor/mcp.json" theme={null}
> {
>   "mcpServers": {
>     "locus-pro": {
>       "url": "https://api.paywithlocus.com/api/credits/mcp",
>       "headers": {
>         "Authorization": "Bearer lcac_...your credential..."
>       }
>     }
>   }
> }
> ```

Hosted model APIs have their own authorization fields. See [Framework integrations](https://docs.paywithlocus.com/locus-pro/frameworks.md). The [Locus CLI](https://docs.paywithlocus.com/locus-pro/cli.md) also accepts an agent key.

## Agent key scope and budgets

A per-call limit caps each charge. A per-run limit (`maxCreditsPerLoop`) caps a whole agent run. To use a run budget, give every paid call in the run the same loop ID. Calls that run at the same time share the budget.

```mermaid theme={null}
flowchart LR
  R["Agent run with loop ID run_42"] --> C1["Call 1"]
  R --> C2["Call 2"]
  R --> C3["Call 3"]
  C1 --> B["One shared run budget"]
  C2 --> B
  C3 --> B
```

| Client | Where to pass the loop ID |
| - | - |
| Node SDK | `{ loopId: "run_42" }` in call options |
| REST | `X-Locus-Agent-Loop-Id: run_42` |
| MCP `execute` | `loop_id: "run_42"` |
| Dedicated MCP tool | `_locus: { "loop_id": "run_42" }` |

Start a new loop ID only for a new run.

## Rotate or revoke an agent key

Manage agent keys in **Connect → API keys**, where their type shows as **Agent**. You can also use the SDK:

```typescript title="Rotate or revoke" theme={null}
const rotated = await locus.agentConnections.rotate(connectionId);
// Save rotated.credential; the old key stops working immediately.

await locus.agentConnections.revoke(connectionId);
```

* **Rotate** issues a new key with the same scope. The old key stops working at once.
* **Revoke** is immediate and permanent. A server key needs only `credentials:manage` to revoke.

For secret and publishable keys, see [Key lifecycle](https://docs.paywithlocus.com/locus-pro/key-lifecycle.md).

## Next steps

> [card] [Framework integrations](https://docs.paywithlocus.com/locus-pro/frameworks.md)
>
> Use the key from your model SDK or agent framework.

> [card] [Paid tool calls](https://docs.paywithlocus.com/locus-pro/paid-tool-calls.md)
>
> See how price caps, approvals, and retries work.

> [card] [Node SDK](https://docs.paywithlocus.com/locus-pro/sdk.md)
>
> Create and manage agent keys from your server.

> [card] [Troubleshoot a connection](https://docs.paywithlocus.com/locus-pro/troubleshoot-agent-connections.md)
>
> Fix sign-in, scope, and budget errors.


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