Agent-native onboarding

An agent can create a restricted Locus Pro account without a Locus dashboard identity, invitation, or existing workspace. Before Locus creates a durable account, the agent must prove a stable AgentID subject and live verified agent inbox through an authorization-code flow. The activated account starts at exactly $0, receives no free or bonus credits, and can manage only its own credential, catalog enablement, funding handoffs, balance, and metered calls.

Start with GET /api/credits/agent/onboarding. It is public and returns the current machine-readable flow, URLs, and security boundaries. Treat that response and the API reference as authoritative.

1. Generate a recovery token

Generate exactly 24 cryptographically random bytes and encode them as unpadded base64url. The result is 32 characters:

import { randomBytes } from "node:crypto";

const registrationToken = randomBytes(24).toString("base64url");

For the shell examples below, generate and retain one token:

export LOCUS_REGISTRATION_TOKEN="$(node -e 'console.log(require("node:crypto").randomBytes(24).toString("base64url"))')"

Store this token like a recovery secret. Locus stores only its digest. Reusing the same account name and token is replay-safe; using the token with different account details returns 409.

2. Begin registration

curl -X POST "https://api.paywithlocus.com/api/credits/agent/register" \
  -H "Content-Type: application/json" \
  -d "{\"name\":\"research-agent\",\"registrationToken\":\"$LOCUS_REGISTRATION_TOKEN\"}"

You can also send agentEmail as an optional AgentID login hint. The verified AgentID token claim remains authoritative. The response envelope is { "success": true, "account": { … } }. The first request returns HTTP 202 with account.onboardingState set to "identity_required", a 15-minute pending registration, and account.registration.authorizationUrl. No account or Locus credential exists yet.

3. Verify with AgentID and replay

Open account.registration.authorizationUrl and approve it with the agent’s AgentID credential. A browserless agent can complete this entirely over HTTP: retain the cookie from the AgentID authorization request, sign the exact 22-character request ID with the inbox’s P-256 key, submit the approval, then call AgentID’s /v0/authorize/continue with the same cookie and follow every redirect. Preserve the final code, state, and iss parameters exactly. The canonical agent/auth.md reference defines the signing payload, approval endpoint, and cookie handling; do not infer them from a search result. The Locus callback validates the issuer, audience, nonce, PKCE exchange, stable subject, and live inbox, then displays a static result page. The callback never returns a Locus credential. Before the pending registration expires, replay the exact same name and registration token:

curl -X POST "https://api.paywithlocus.com/api/credits/agent/register" \
  -H "Content-Type: application/json" \
  -d "{\"name\":\"research-agent\",\"registrationToken\":\"$LOCUS_REGISTRATION_TOKEN\"}"

Activation returns 201 for a new account or 200 for an existing, renewed, or recovered account. Store account.connection.credential immediately. It is an lcac_… compatibility credential for the authenticated account-management REST calls on this page; Locus reveals it only on registration replay and rotation.

export LOCUS_AGENT_CREDENTIAL="lcac_..."

Read the account at any time:

curl "https://api.paywithlocus.com/api/credits/agent/account" \
  -H "Authorization: Bearer $LOCUS_AGENT_CREDENTIAL"

The response reports the exact decimal-string balance, credential expiry, useful links, and onboardingState: funding_required or ready.

4. Connect the agent through MCP OAuth

Configure this Streamable HTTP MCP URL in a client with native OAuth:

https://api.paywithlocus.com/api/credits/mcp

At the Locus authorization screen, choose AgentID and approve with the same identity used during registration. The MCP client stores and refreshes its own OAuth tokens. Use this OAuth connection for tools; do not paste the lcac_… compatibility credential into an interactive MCP client. On a headless host, keep the MCP client’s login process and loopback listener alive. Follow its authorization URL, retain the request=lmo_req_… handle from the Locus consent URL, and read the signed-out context:

curl "https://api.paywithlocus.com/api/credits/mcp/oauth/authorize/public-context?request=$LOCUS_MCP_REQUEST"

Follow data.agentIdAuthorizationUrl with a cookie jar, complete the same browserless AgentID approval used for registration, and follow the redirects back to the MCP client’s exact callback URI. Supply a final callback URL or code manually only when that client explicitly supports it. See Connect agents for the complete handoff.

5. Find and enable capabilities

Search includes disabled entries so an agent can discover an exact slug before enabling it:

curl -X POST "https://api.paywithlocus.com/api/credits/agent/catalog/search" \
  -H "Authorization: Bearer $LOCUS_AGENT_CREDENTIAL" \
  -H "Content-Type: application/json" \
  -d '{ "query": "current web evidence", "limit": 5 }'

Enable one exact ordinary-provider result, such as tavily/search. Agent-owned accounts can change only the enabled flag; they cannot change pricing or other tenant settings. The system-managed router provider is not mutable through this endpoint.

curl -X PUT "https://api.paywithlocus.com/api/credits/agent/catalog" \
  -H "Authorization: Bearer $LOCUS_AGENT_CREDENTIAL" \
  -H "Content-Type: application/json" \
  -d '{ "slug": "tavily/search", "enabled": true }'

6. Hand funding to a payer

First read the live constraints:

curl "https://api.paywithlocus.com/api/credits/agent/funding/config" \
  -H "Authorization: Bearer $LOCUS_AGENT_CREDENTIAL"

Then create an exact-amount Stripe Checkout handoff. Reuse the same Idempotency-Key when retrying the same logical handoff.

curl -X POST "https://api.paywithlocus.com/api/credits/agent/funding-sessions" \
  -H "Authorization: Bearer $LOCUS_AGENT_CREDENTIAL" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "usd": "20.00" }'

Send the payer the returned humanHandoff.message or checkoutUrl. It expires after one hour. The payer does not become the account owner, and the card is not attached for future use or delegated to the agent. Never ask the payer to send card details through chat. Poll the authenticated statusUrl no faster than pollAfterMs. Continue only when state is ready: that state means the signed Stripe webhook has been consumed and the ledger balance is usable. A browser return or Stripe payment status alone is not enough.

State	Meaning	Next action
`awaiting_payment`	The Stripe Checkout Session is open and unpaid	Keep the current link until it expires
`processing`	Stripe reports payment, but the durable ledger update is not complete	Poll again after `pollAfterMs`
`ready`	The payment webhook was consumed and the balance is usable	Continue to Locus tools
`expired`	The link expired before credits became usable	Create a new funding session
`failed`	Payment or credit issuance reached a terminal failure	Check the prior attempt before creating a new link

7. Use Locus

Use the MCP OAuth connection for tool discovery and execution. Keep the lcac_… compatibility credential for the agent-account, catalog, funding, and rotation REST routes documented by this flow. It works only for its agent-owned account; tenant-managed Agent Connection endpoints reject it where the two account models must stay separate.

Rotate the credential

Generate a new 24-byte base64url recovery token, then rotate while the current credential is still valid:

export LOCUS_NEW_REGISTRATION_TOKEN="$(node -e 'console.log(require("node:crypto").randomBytes(24).toString("base64url"))')"

curl -X POST "https://api.paywithlocus.com/api/credits/agent/credential/rotate" \
  -H "Authorization: Bearer $LOCUS_AGENT_CREDENTIAL" \
  -H "Content-Type: application/json" \
  -d "{\"registrationToken\":\"$LOCUS_NEW_REGISTRATION_TOKEN\"}"

Rotation atomically replaces both the recovery digest and bearer credential, returns the new lcac_… value once, and extends expiry by 365 days. Replace the stored credential and recovery token together.

Never send the bearer credential or registration token to a payer. The public funding status contains only the funding state, agent display name, and credited amount.

Getting started

Funding & billing

Catalog

Agents

Developer tools

Testing

Agent-native onboarding

1. Generate a recovery token

2. Begin registration

3. Verify with AgentID and replay

4. Connect the agent through MCP OAuth

5. Find and enable capabilities

6. Hand funding to a payer

7. Use Locus

Rotate the credential

​1. Generate a recovery token

​2. Begin registration

​3. Verify with AgentID and replay

​4. Connect the agent through MCP OAuth

​5. Find and enable capabilities

​6. Hand funding to a payer

​7. Use Locus

​Rotate the credential

1. Generate a recovery token

2. Begin registration

3. Verify with AgentID and replay

4. Connect the agent through MCP OAuth

5. Find and enable capabilities

6. Hand funding to a payer

7. Use Locus

Rotate the credential