Authentication and scopes

Give each integration the access it needs. Keep tenant secret keys on trusted servers, use scoped Agent Connections for unattended agents, and connect interactive MCP clients through OAuth. The keys and workspace roles on this page are Locus Pro Enterprise features. For self-serve setup, see Connect your agent.

Choose a credential

Credential	Use it for
Dashboard session	Human administration, limited by workspace role
Tenant secret key (`lcr_…`)	Trusted-server calls and scoped management API access
Publishable key (`lcrpk_…`)	Browser/widget pairing; it cannot authorize calls by itself
End-user token	Calls and balance access for one customer
Agent Connection (`lcac_…`)	An unattended agent with an expiry, allowed tools, and optional spending limits
Sandbox key (`lcrsb_…`)	Simulated direct calls with no provider requests or credit charges

An Agent Connection keeps an agent tied to its assigned account and limits. Use it when the credential will live inside an agent runtime. Use a sandbox key for integration tests.

Issue and revoke safely

Verify your identity

Create a scoped key

Open API Keys and choose the scopes your integration needs.

Store and test

Save the raw value in your server’s secret manager. Locus shows it only once. Check access and test the integration before retiring the old credential.

You can rotate a key with a grace period so the old and new values overlap during deployment. Revoke credentials that are no longer in use and review the credential audit in the dashboard.

Never put a tenant secret key in browser code, a mobile app, a prompt, or a source repository. For customer-facing browser features, issue a short-lived end-user token on your server.

Enterprise management scopes

Scope	Access
`tenant:read`	Workspace, catalog, balance, usage, ledger, and billing reads
`tenant:write`	Workspace settings and webhook replay
`catalog:write`	Tool enablement and pricing
`credits:move`	Credit allocation, top-ups, and secret-key metered calls
`credentials:manage`	Key, Agent Connection, and webhook-secret lifecycle
`tokens:manage`	End-user policies and token lifecycle
`payouts:manage`	Auto-recharge and payout settings
`members:manage`	Workspace membership
`widget:read`	Reserved scope attached to publishable keys

Scopes do not override workspace roles. Sensitive changes, including API-key lifecycle, membership, spend controls, and payout settings, require a workspace owner or admin with recent MFA or passkey verification. An API key cannot satisfy that requirement. Custom API changes remain owner-only.

Automating Agent Connections

A server key with both credentials:manage and credits:move can create or rotate Agent Connections without human verification. Revocation needs only credentials:manage. Dashboard callers need an owner or admin role and recent verification.

Enterprise workspace roles and invitations

Role	Typical access
Owner	Full workspace administration, including Custom API changes
Admin	Team, keys, billing, spending controls, catalog, and integrations
Developer	Catalog configuration and pricing; inspect Agent Connections and integration data
Billing	Billing and usage reads; funding changes require an owner or admin
Viewer	Read-only balances, usage, analytics, and membership

Custom API changes are restricted to the owner. The original owner cannot be removed or reassigned. An owner or admin can invite members from Team. Assign one non-owner role to each invitee. Invitations expire after seven days; an owner or admin can resend or revoke them. Membership changes require recent MFA or passkey verification.

Check access

Use the credential endpoint to see the current credential’s scopes and role:

curl --fail-with-body \
  https://api.paywithlocus.com/api/credits/auth/credential \
  -H "Authorization: Bearer $LOCUS_SECRET_KEY"

The response contains authorization metadata, never the raw secret. Dashboard sessions with multiple workspace memberships must also identify the active workspace with X-Locus-Tenant-Id.

Handle authorization errors

Response	What to do
`401`	Check the credential type, expiry, and revocation status
`403 INSUFFICIENT_SCOPE`	Use a credential with the required scope
`STEP_UP_REQUIRED`	Have an owner or admin complete MFA or passkey verification; Custom API changes require the owner

Repeating the same request does not resolve missing access. The API reference lists each route’s requirements. See Account setup for sign-in methods.

Getting started

Build with Locus Pro

Connect agents

Funding & billing

Developer tools

Catalog directory

Testing

Authentication and scopes

Choose a credential

Issue and revoke safely

Enterprise management scopes

Automating Agent Connections

Enterprise workspace roles and invitations

Check access

Handle authorization errors

​Choose a credential

​Issue and revoke safely

​Enterprise management scopes

​Automating Agent Connections

​Enterprise workspace roles and invitations

​Check access

​Handle authorization errors

Choose a credential

Issue and revoke safely

Enterprise management scopes

Automating Agent Connections

Enterprise workspace roles and invitations

Check access

Handle authorization errors