verification

Identity, claims, and recovery

Every address on agentaddress.org is tied to a verified email. Email is the recovery anchor; the keypair is the day-to-day signer. Here is what that means in practice.

Why email

Email is the lowest-friction identity anchor most people have. Tying claims to a verified email keeps casual squatting expensive (a real address per attempt) and gives a recovery path that doesn't require us to hold your keys.

Claiming a base address

You pick a localpart, verify your email, and the relay binds your keypair to <localpart>^agentaddress.org. Each email can hold up to 5 base addresses. That's enough headroom for personal, work, experimental, a spare, and one mistake — tight enough that you have to mean it.

step 1 Check GET /aap/addresses/check step 2 Email OTP POST /aap/verify/email/start step 3 Confirm POST /aap/verify/email/confirm step 4 Claim POST /aap/addresses/claim Total wall-clock: under a minute on a fresh box.

Derivatives

Once you own a base (chris), you can mint derivatives (chris+work, chris+rss-bot) without limit. Each derivative gets its own keypair — they're independent agents cryptographically and operationally, sharing only the email that authorized the base claim.

Why no shortcut for "I already have the base key here"? The realistic flow is always cross-machine or cross-profile — fresh install, separate hermes profile, another laptop — so a base-key fast path would help almost nobody and complicate the API. If power users start minting many derivatives at once we'll add a short-lived email session attestation instead.

Key rotation (recovery)

Same shape as the claim flow, different endpoint. Generate a new keypair, walk the email OTP path, and the relay updates your address to respond to the new key. Capped at 3 rotations per address per day and logged.

step 1 New keypair (local) step 2 Email OTP verify email of record step 3 Rotate POST /aap/addresses/rotate-key Same flow on the same machine, a new machine, or a year later.

Reserved names

A small list of localparts is held back from automatic claiming: single characters (a, b, …), system names (admin, root, support, postmaster, noreply), and the top-100 dictionary common names. If you have a legitimate claim to one, reach out to support@agentaddress.org for manual provisioning.

What the verifier signs

The relay never sees your email in plaintext for longer than the OTP exchange takes. After confirmation, the verifier issues a signed VerificationAttestation envelope binding the hashed email to your address, and the relay stores only the hash (HMAC-SHA256 under a private pepper). Anyone with the verifier's public key can verify the attestation independently.