auth.md
Flow

User claimed

The agent registers without a provider-attested identity; the user claims it by signing in to your service and confirming a code the agent shows them. No agent-provider participation — just the app and the user.

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 claim 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 pre-claim identity_assertion immediately, which it exchanges for an access_token scoped to pre-claim permissions you define. The agent can run the claim ceremony at any point before the registration expires to bind the registration 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 (service_auth)

Agent supplies a user email at registration as a login_hint. Your service returns the ceremony materials but withholds the assertion until the user completes the claim.

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

How the claim ceremony works

The ceremony borrows the RFC 8628 device-authorization shape. Your service never emails the code — the code travels from the agent to the user, and the user confirms it on a page you own.

  1. Your service mints a 6-digit user_code and a verification_uri (returned in the registration response for service_auth, or from /agent/identity/claim for anonymous start).
  2. The agent surfaces the user_code and link to the user in one message.
  3. The user opens the link, signs in (or signs up) at your service, and lands on a page you own that displays the registration.
  4. The user types the user_code into that page and submits. Your service matches them to an account and marks the claim complete.
  5. The agent — which has been polling /oauth2/token with the claim grant — receives an access_token and a service-signed identity_assertion. Anonymous start upgrades the registration's scopes in place; service_auth gets its first assertion here.

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.
  • The user authenticates through your own sign-in flow, so whatever you enforce there — SSO, MFA, bot detection — applies to the claim with no agent-auth-specific exceptions.
  • Optionally: agents can be productive from second one (anonymous start) instead of waiting for the human to confirm.

Trade-offs

  • More state to manage than agent verified — a pre-claim registration, a claim state machine, a user_code store, a scope swap.
  • You own a user-facing claim page where the signed-in user types the user_code.
  • 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.