Authentication and scopes

Locus Pro credentials are deliberately not interchangeable. Use the narrowest credential that can perform the operation, and never place a tenant secret key or dashboard token in an agent runtime or browser.

Personal accounts authenticate the dashboard with a human session and connect MCP clients through OAuth. They do not issue tenant, publishable, or sandbox keys and do not expose end-user, member, margin, or metering administration. The key lifecycle, management scopes, and workspace roles below are enterprise features unless stated otherwise.

For enterprise development and CI, prefer a sandbox key: it runs the metered request contract end to end without moving credits and carries no management authority at all. On Create your Locus account, email/password signup verifies the email; configured Google, GitHub, and GitLab options create a Personal account from the provider identity; and Ethereum signup proves wallet control plus a recovery email. On Sign in, email/password and passkeys authenticate directly, external providers resolve an existing identity, and Ethereum requires a wallet that is already linked. Sign-in does not create a second account. Manage linked providers and wallets from Account security while recently authenticated. Wallet sign-in asks for an EIP-4361 message signature, not a transaction or access to funds. A wallet must be linked before it can sign you in. If the account has managed SMS or TOTP MFA, use a password or passkey so Cognito can enforce the enrolled factor. See Account setup and sign-in for personal-account creation, workspace invitations, and interrupted-signup recovery.

Credential matrix

Credential	Availability	Prefix or source	Intended use	Management API	Metered calls	Human step-up
Dashboard session	Personal and enterprise	Credits Cognito user	Human administration	Personal-account routes, or enterprise routes limited by membership role and scopes	No	Enterprise owners can complete MFA step-up
Tenant secret key	Enterprise	`lcr_…`	Trusted server integration	Yes, limited by the key’s scopes	Yes	Never eligible
Publishable key	Enterprise	`lcrpk_…`	Browser/widget pairing	No	No by itself	Never eligible
End-user token	Enterprise	Signed JWT	One tenant end user	No	Yes, only as that end user	Never eligible
Managed agent connection credential	Enterprise	`lcac_…`	One headless agent, held to a fixed account and expiry plus configured endpoint and budget limits	No	Yes, within the connection’s identity, endpoint, call, and loop controls	Never eligible
Sandbox key	Enterprise	`lcrsb_…`	Test-only integration runs	No	Simulated only — no credits move, no providers are called	Never eligible

Agent-native onboarding also returns an lcac_… compatibility credential for the self-registered Personal account. It authorizes only the explicit agent-account setup and maintenance routes documented in the onboarding flow. Use native MCP OAuth, not that compatibility credential, for ordinary tool use. The agent connection row is the odd one out. An lcac_… value is issued by an agent connection, a saved configuration that pins the account and expiry the credential must obey, plus any endpoint allowlist and spend limits you choose to set — so the credential is one field of a larger object rather than a standalone key. See what an agent connection is for how it differs from a tenant secret key, and why the two are not interchangeable even though both can authenticate a metered call.

Enterprise management scopes

Scope	Route families it authorizes
`tenant:read`	Tenant profile; catalog/models/pricing reads; analytics, ledger, webhook events, end users and policy history; earnings, Stripe/commercial status, generated docs, spend-control and top-up reads (including the top-up quote), and balance reads
`tenant:write`	Tenant profile/settings changes, workspace spend controls, and webhook-event replay
`catalog:write`	Global, bulk, provider, and endpoint catalog configuration
`credits:move`	Allocate/deallocate credits, initiate a top-up, and secret-key metered execution
`credentials:manage`	API-key, Agent Connection, credential-audit, security-audit, and webhook-secret lifecycle
`tokens:manage`	End-user policy changes and end-user token issue/list/revoke
`payouts:manage`	Auto-recharge, Stripe Connect authorize/disconnect, and payout-destination settings
`members:manage`	Invite, resend, revoke, change the role of, and remove workspace members
`widget:read`	Reserved. It is the only scope a publishable key can hold, and it is attached automatically. No route checks it today. The end-user token authorizes widget API requests; an optional publishable key must belong to the same tenant.

Possessing a scope is necessary but not always sufficient. Workspace roles set the maximum scopes for a human member. High-risk operations such as API-key lifecycle, workspace membership changes, webhook-secret rotation, spend-control changes, auto-recharge, payout-destination changes, and Stripe Connect require the Cognito workspace owner with the applicable scope and MFA or passkey step-up completed in the last ten minutes. Admins, developers, billing members, viewers, and tenant secret keys cannot satisfy that owner boundary, even if their stored scopes contain the named scope. One deliberate exemption: Agent Connection create, rotate, and revoke can be automated by a tenant secret key holding credentials:manage, with no step-up, so servers can rotate short-lived agent credentials on their own.

Enterprise workspace roles and invitations

Locus Pro workspaces support these human roles:

Role	Default access
Owner	Full workspace access. The original owner cannot be removed or reassigned.
Admin	Workspace settings, billing, catalog, credentials, and developer tools within owner-only route boundaries
Developer	Catalog, credential metadata, Agent Connections, end-user tokens, and integrations within owner-only route boundaries
Billing	Funding, credit allocation, and billing reads within owner-only payout and payment-setting boundaries
Viewer	Read-only access to balances, usage, analytics, and workspace membership

Only an owner can invite up to 20 email addresses at once from Team. The page title is Members. Each invitation assigns one non-owner role and expires after seven days. The recipient follows the single-use email link, signs in or creates the invited identity, and joins the existing workspace. Inviting, resending, revoking, changing a role, or removing a member requires recent MFA or passkey step-up.

Do not share a dashboard login between people. Invite each person separately and assign the narrowest role they need. Tenant API keys cannot list human member email addresses or manage workspace membership.

Preflight the current credential

Before attempting a management operation, inspect the credential against the same deployed API you will call:

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

The response contains only authorization metadata:

{
  "success": true,
  "credential": {
    "auth": "secret_key",
    "tenantId": "11111111-1111-4111-8111-111111111111",
    "role": "owner",
    "credentialId": "key-record-id",
    "scopes": ["credits:move", "tenant:read"],
    "stepUpEligible": false,
    "stepUpFresh": false
  }
}

It never returns the raw credential, a key hash, Cognito claims, or an end-user token. Dashboard users with more than one membership must also send the exact X-Locus-Tenant-Id header.

Handle authorization errors

A missing scope returns HTTP 403 with stable machine-readable evidence:

{
  "success": false,
  "error": "Forbidden",
  "code": "INSUFFICIENT_SCOPE",
  "message": "Required credits scope: catalog:write",
  "requiredScopes": ["catalog:write"],
  "presentScopes": ["tenant:read"]
}

Do not retry this response. Issue or rotate a deliberately scoped credential, or use the dashboard owner flow when the route requires human step-up. STEP_UP_REQUIRED means the owner must sign in with MFA again; it does not mean an API key should be granted more authority. A 401 means the credential is missing, malformed, expired, revoked, or the wrong credential type for that surface.

Issue and revoke safely

Sign in as the workspace owner with credentials:manage and complete MFA or passkey step-up.
Issue a new credential with only the required scopes and, when supported, an expiry.
Store the raw value immediately in the intended server-side secret store. Locus returns it only once.
Call the credential preflight endpoint and one non-destructive target route.
Move the integration to the new credential.
Revoke the old credential and confirm it receives 401 while the new credential continues to work.
Review the credential/security audit in the dashboard.

To replace one credential in place, POST /api/credits/tenants/me/keys/KEY_UUID/rotate performs steps 2–6 as a single operation: the replacement inherits the key’s name, scopes, endpoint allowlist, pricing, and expiry; the superseded key keeps working for the requested gracePeriodSeconds overlap (capped at its own expiry) while every other key is untouched. PATCH /api/credits/tenants/me/keys/KEY_UUID renames a key without touching the credential; the audit trail records the previous name. For agent runtimes, create an Agent Connection rather than sharing lcr_…. Agent Connections are also returned once and should be constrained to the required endpoints and optional per-call/per-loop limits.

Getting started

Funding & billing

Catalog

Agents

Developer tools

Testing

Authentication and scopes

Credential matrix

Enterprise management scopes

Enterprise workspace roles and invitations

Preflight the current credential

Handle authorization errors

Issue and revoke safely

​Human signup and sign-in

​Credential matrix

​Enterprise management scopes

​Enterprise workspace roles and invitations

​Preflight the current credential

​Handle authorization errors

​Issue and revoke safely

Human signup and sign-in

Credential matrix

Enterprise management scopes

Enterprise workspace roles and invitations

Preflight the current credential

Handle authorization errors

Issue and revoke safely