The auth.md protocol

Agents find your app through three public files. Host them yourself or let NoForm serve them at /a/<slug>:

• GET {BASE}/auth.md — the markdown contract: identity model, scopes, and the signup steps.
• GET {BASE}/.well-known/oauth-protected-resource — RFC 9728 resource metadata.
• GET {BASE}/.well-known/oauth-authorization-server — AS metadata plus an agent_auth block advertising the register / claim / complete / revoke / verify endpoints.

Four POSTs take a human from “never heard of your app” to an email-verified account. The agent drives; the human only reads one code from their inbox.

POST {BASE}/agent/auth
{ "email"?: "user@acme.com", "agent_platform"?: "claude" }

→ 201 { "credential", "claim_token", "scopes", "expires_at" }   (anonymous)
→ 201 { "claim_token", "expires_at" }                           (email-required)

POST {BASE}/agent/auth/claim
{ "claim_token": "…", "email": "user@acme.com" }

→ 200 { "ok": true }   // 6-digit code emailed; 3/h per inbox, 10/h per IP

POST {BASE}/agent/auth/claim/complete
{ "claim_token": "…", "otp": "123456" }

→ 200 { "status": "active", "scopes": ["read","write"] }

POST {BASE}/agent/auth/revoke
{ "credential": "nf_live_…" }

If you configure a post-signup login link, the register response also returns login_url with the credential already embedded — one clickable link for the agent to hand the user.

When the user arrives at your /welcome handler with a credential, validate it server-side with your API key:

POST {BASE}/agent/auth/introspect
Authorization: Bearer <your nf_live_ API key>
{ "credential": "nf_live_…" }

→ 200 { "active": true, "email": "user@acme.com", "scopes": [...], "sub", "expires_at" }
→ 200 { "active": false }      // unknown / expired / revoked
→ 401                          // missing or invalid API key

active: truemeans a real, email-verified human — start your own session and you're done.

Trust specific agent platforms cryptographically and skip the human step. Configure the issuer and its JWKS URI in the dashboard; the platform then provisions accounts with a signed JWT:

POST {BASE}/agent/auth/verified
Authorization: Bearer <jwt with iss, aud, sub, exp, jti>

→ 201 { "credential": "nf_live_…", "status": "active" }
→ 409                          // replayed jti — each token is single-use

Every protocol action lands in your audit log: registration.created, claim.requested, claim.confirmed, verified.accepted, registration.revoked, ratelimit.blocked, cap.blocked, abuse.flagged and more. Subscribe a webhook in the dashboard and each delivery is signed with HMAC-SHA256 in the X-NoForm-Signature header. Failed deliveries (timeout or non-2xx) are recorded as webhook.failed in the audit log.