API keys

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.

​

Which key do I need?

For an agent your customer runs and pays for, use an agent key for that one end user, or an end-user token. 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.

​

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 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, 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 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 to show a customer their balance or let them top up. See the widget.

​

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.

​

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.

​

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

​

Rotate and revoke

Rotating gives a key a new value with the same settings. Revoking is immediate and permanent. See Key lifecycle 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.

​

Next steps