auth.md
Flow

User claimed

The agent registers without a provider-attested identity, and the user binds the registration to their account by reading a one-time code from an email back to the agent. Doesn't require any agent-provider participation — the app and the user run the whole ceremony.

When to use it

  • Your users run agents on platforms that can't mint ID-JAGs — MCP servers, custom scripts, bare LLM API integrations.
  • You want to support self-serve agent registration without curating a provider trust list.
  • You're comfortable owning the OTP ceremony and the registration state machine.

Two entrypoints

The user claimed flow has two starting shapes — your app picks which one (or both) to allow.

Anonymous start

Agent self-registers without identity and gets a credential immediately, scoped to pre-claim permissions you define. The agent can run the OTP claim at any point before the registration expires to bind the credential to a real user and upgrade to full scopes.

Best when uninterrupted setup matters more than upfront identity — the agent can start doing useful work right away.

Email required

Agent supplies a user email at registration. Your service emails the OTP and withholds the credential until the agent reads the code back and completes the claim.

Best when pre-claim usage is unacceptable — the credential never exists until a verified user is bound to it.

How the OTP ceremony works

  1. Agent (or the agent + user) initiates the claim by giving your service an email address.
  2. Your service emails the user a one-time URL that lands on a page displaying a 6-digit OTP.
  3. The user reads the OTP back to the agent.
  4. Agent POSTs the OTP to /agent/auth/claim/complete.
  5. Your service verifies the OTP, matches the user to an account, and either upgrades the existing credential's scopes (anonymous start) or issues a fresh credential (email required).

What you get

  • Self-serve agent onboarding that works without any provider integration.
  • A real user binding once the claim completes, with a revoke surface the user controls.
  • Optionally: agents can be productive from second one (anonymous-start) instead of waiting for the human to be available to read an OTP.

Trade-offs

  • More state to manage than agent verified — a pre-claim principal, a claim state machine, an OTP store, a scope swap.
  • OTPs are user-facing — you'll need the email infrastructure and a server-rendered code page.
  • Anonymous-start credentials exist before a user is bound; key material captured pre-claim retains access post-claim with the new scopes unless you force-rotate.

Implement it

App side: For apps → user claimed flow. No agent-provider integration needed.