Skip to main content
Every AFAuth service publishes a JSON discovery document at https://{host}/.well-known/afauth. Agents fetch it to learn the service’s DID, where its endpoints live, and which optional features and billing rules apply. It is unauthenticated and cacheable.
The normative JSON Schema is AFAuthHQ/spec/schemas/well-known.json (rendered at /spec/well-known). This page is the human-readable field reference; the schema is the source of truth.

​
Example

{
  "afauth_version": "0.1",
  "service_did": "did:web:api.example.com",
  "endpoints": {
    "accounts":         "/afauth/v1/accounts",
    "owner_invitation": "/afauth/v1/accounts/me/owner-invitation",
    "claim_page":       "https://api.example.com/afauth/claim",
    "claim_completion": "/afauth/v1/claim/complete",
    "key_rotation":     "/afauth/v1/accounts/me/keys/rotate"
  },
  "signature_algorithms": ["ed25519"],
  "features": ["attestation", "key_rotation", "attested_session"],
  "recipient_types": ["email"],
  "limits": {
    "unclaimed_rate_limit_per_hour": 100
  },
  "billing": {
    "unclaimed_mode": "attested_only",
    "accepted_attestors": ["afauth-trust"]
  }
}

​
Required fields

FieldTypeNotes
afauth_versionstringProtocol version this service supports, e.g. "0.1".
service_didstringThe service’s own DID. did:web: is RECOMMENDED (identity anchored in DNS + TLS); did:key: is permitted but lacks an authority anchor. Must match ^did:(web|key):.+.
endpointsobjectEndpoint map (below). accounts, owner_invitation, claim_page, claim_completion are all required.
signature_algorithmsstring[]Non-empty. Each entry is "ed25519" or "ecdsa-p256-sha256".

​
endpoints

KeyRequiredNotes
accountsyesAccount introspection / implicit-signup endpoint.
owner_invitationyesWhere the agent stages an owner-invitation (step 1 of the ceremony).
claim_pageyesFull URI (not a path) of the human-facing claim page.
claim_completionyesWhere the claim is finalized (step 2).
key_rotationnoPresent only if the service supports key_rotation.
Endpoint values are paths relative to the service host, except claim_page, which is a full URI.

​
Optional fields

FieldTypeNotes
featuresstring[]Optional capabilities. Allowed values: "attestation", "key_rotation", "attested_session" (the service maintains §10.7 attested sessions — periodic re-presentation). Two-step invite is mandatory in v0.1 and is not advertised here.
recipient_typesstring[]Recipient types accepted on the owner-invitation endpoint. Allowed: "email", "phone", "oidc", "did". Absent means email-only.
limitsobjectunclaimed_rate_limit_per_hour (integer ≥ 0), plus the optional unclaimed_ttl_seconds (integer ≥ 3600). Omit unclaimed_ttl_seconds for no expiry — the default and recommended posture; set it only to garbage-collect abandoned accounts or meet a retention mandate (§4.4).
billingobjectRequires unclaimed_mode ∈ "free" / "attested_only" / "denied". Optional accepted_attestors (string[]) names the attestor iss values the service trusts, e.g. ["afauth-trust"].
x402objectOpt-in advertisement of x402 (HTTP 402) payment acceptance. Requires facilitator, networks, assets, payment_endpoint.

​
Forward compatibility

Unknown top-level fields MUST be accepted and ignored (§4.2) — consumers parse forward-compatibly so the document can grow without breaking older agents. Well-formed and malformed examples live in vectors/discovery/.