Agent keys

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.

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.

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

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.

Dashboard
From your backend

Start a new key

Open Connect → API keys, select Create key, and choose An agent.

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.

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.

List the exact provider/endpoint slugs the agent needs:

Create an agent key

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.

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.

Codex
Claude Code
Cursor

Add to ~/.codex/config.toml:

~/.codex/config.toml

[mcp_servers.locus_pro]
url = "https://api.paywithlocus.com/api/credits/mcp"
bearer_token_env_var = "LOCUS_AGENT_CONNECTION"

: "${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.

Add to .cursor/mcp.json and keep this file out of source control:

.cursor/mcp.json

{
  "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. The Locus CLI 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.

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:

Rotate or revoke

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.

Next steps

Framework integrations

Use the key from your model SDK or agent framework.

Paid tool calls

See how price caps, approvals, and retries work.

Node SDK

Create and manage agent keys from your server.

Troubleshoot a connection

Fix sign-in, scope, and budget errors.

Getting started

Build with Locus Pro

Connect agents

Pricing & plans

Funding & billing

Developer tools

Catalog directory

Testing

How it works

Create an agent key

What you choose

What you can change later

Agent key configuration

Agent key scope and budgets

Rotate or revoke an agent key

Next steps

Framework integrations

Paid tool calls

Node SDK

Troubleshoot a connection

​How it works

​Create an agent key

​What you choose

​What you can change later

​Agent key configuration

​Agent key scope and budgets

​Rotate or revoke an agent key

​Next steps

Framework integrations

Paid tool calls

Node SDK

Troubleshoot a connection

How it works

Create an agent key

What you choose

What you can change later

Agent key configuration

Agent key scope and budgets

Rotate or revoke an agent key

Next steps