skip to content
agentregistrar_

How it works

The end-to-end brokered signup handshake, the claims a provider verifies and what revocation changes.

awaiting reviewupdated view markdown ->

A brokered signup is five steps and one artifact. The human signs one master agreement, the agent gets an identity, the broker mints a short-lived proof for each service acceptance, the provider verifies it, and the broker records what happened.

The handshake

Brokered signup handshake between the human owner, the agent, the broker and the providerNumbered eight-step flow. Step 1, human: sign in with GitHub, verify the email address and sign the master delegation agreement. Step 2, agent: connect the harness to the broker MCP endpoint and complete OAuth in the browser. Step 3, broker: identity_register returns the agent sub-identity, the inbox address and the delegated scopes. Step 4, agent: fetch the provider discovery document and recompute the terms hash. Step 5, broker: identity_prove records the ToS acceptance, mints the assertion (a JWT plus the same claims for inspection) and sends the ledger receipt to the agent inbox and to the human owner. Step 6, agent: POST assertion.jwt to the provider agent_signup endpoint as an Authorization Bearer token. Step 7, provider: verify the assertion, create or resolve the account, return the signed receipt and the context pointer. Step 8, broker: identity_record_signup records the signup proof in the human owner's ledger. Three trust boundaries are marked: human consent after step 1, broker minting after step 5, and provider verification after step 7.HUMAN1sign in with GitHub, verify your email,sign the master agreementTRUST BOUNDARY - HUMAN CONSENTAGENT2connect the harness to the MCP endpointand complete OAuth in the browserBROKER3identity_register: sub-identity, inboxaddress and delegated scopesAGENT4fetch the provider discovery documentand recompute the terms hashBROKER5identity_prove records the acceptance,mints the assertion, sends ledger mailTRUST BOUNDARY - BROKER MINTINGAGENT6POST assertion.jwt to agent_signupas Authorization: BearerPROVIDER7verify the assertion, create or resolvethe account, return receipt + contextTRUST BOUNDARY - PROVIDER VERIFICATIONBROKER8identity_record_signup records theproof in the human owner's ledger
Hand-authored, not normative. The contract is the specification; this figure is an orientation aid.

Diagram legend, eight events: 1 human consent, 2 connect, 3 register, 4 discover, 5 prove, 6 post, 7 verify, 8 record. The dashed rules mark the three trust boundaries: human consent after step 1, broker minting after step 5, provider verification after step 7.

The five steps below are the same flow at a coarser grain than the diagram's eight events.

  1. Register. The harness connects to the broker's MCP endpoint at https://agentregistrar.dev/mcp and completes OAuth in the browser. identity_register returns the agent sub-identity: id, inbox address and delegated scopes.
  2. Discover. The agent calls identity_signup with the service and the exact accepted terms text. The broker fetches /.well-known/agent-signup.json, checks the protocol value, the issuer allowlist and the required scopes, recomputes the SHA-256 of terms.text, verifies any optional provider verification credential against the RP broker's JWKS, and applies the human's allow/warn/require/block policy.
  3. Prove. identity_signup records a delegated acceptance for the human owner and mints the assertion. The call is side-effecting: it writes a durable consent row and sends the ToS Acceptance Ledger email to the agent inbox plus a forward to the human. identity_prove is the advanced equivalent when you need the raw claims or an explicit discovery source.
  4. Sign up. The agent posts assertion.jwt as Authorization: Bearer <assertion> to the single endpoint endpoints.agent_signup. The provider verifies the assertion, creates or resolves the account, and returns an RP-signed receipt and usually a context pointer.
  5. Record. identity_record_signup verifies the RP-signed signup_token against the exact historical attestation and stores the proof against the human's ledger. The result carries a handoff reminder: store any provider credential now, and never re-run signup to recover one.

The diagram is not normative. The contract is section 3 and section 7 of the specification.

What the provider sees

The assertion is a signed JWT with four claim groups. The provider must verify the signature against the issuer's JWKS before trusting any of it.

Claim Meaning What the provider checks
iss Broker origin Exact match against an entry in issuer_allowlist; JWKS fetched from that origin
aud Service audience Equals the discovery audience
jti Assertion id Not reused in a conflicting context; a repeat for the same account resolves
iat, exp Issued and expiry Not expired, allowing at most 60 seconds of clock skew; a lifetime of about five minutes is expected
agent.id, agent.name, agent.email, agent.harness Agent identity Stable key for attribution
human.id, human.name, human.email Human principal Stable across that human's agents
human.verified Email verification flag Must be true
delegation.accepted_rp_tos_url, delegation.accepted_rp_tos_hash The accepted terms URL matches terms.url; hash equals the current terms.sha256
delegation.accepted_at Original consent time The durable acceptance time, not the mint time
delegation.scopes Delegated scopes Covers every required_scopes entry
delegation.master_tos_version Master agreement version Informational

A provider keys an account on (iss, human.id) for one account per human, or on (iss, agent.id) for one account per agent. Keying on email creates duplicates when an address changes, and agent addresses are broker-controlled.

Where email fits

The broker's inbox is part of the handshake, not an add-on.

  • The acceptance receipt goes to the agent inbox and is forwarded to the verified human email. That is the human's record of what was accepted.
  • Provider welcome mail and legal receipts go to the agent's inbox address.
  • If a provider verifies by email, the six-digit code arrives in the same inbox and is read with inbox_read or inbox_wait_for_email as detected_otp.

Revocation and retries

Revocation and suspension. The kill switch sets the agent to revoked; an operator protective action after a verified abuse report sets suspended. New identity_signup/identity_prove calls fail with agent_revoked (a suspension uses the same code with a suspension message), and the identity and inbox tools reject the agent at the gate. identity_record_signup still accepts a receipt the provider already issued. An assertion already minted and handed to a provider stays valid until it expires, at most five minutes, because the provider verifies it offline. Neither state deletes a provider account, revokes a provider credential, or undoes an accepted ToS.

Retries. Identical identity_signup/identity_prove calls while the assertion is unexpired return the same JWT, with reuse.reused: true, and create no new acceptance and no new ledger mail; every gate and policy still re-run. After expiry a fresh assertion references the same acceptance and the original consent time. On the provider side, a repeated signup for the same account resolves idempotently and reports resolution: "resolved", which is a success.

Next

edit page -> githubreport issue
sections

type to search.

up/down navigateenter selectesc close