# registry.afauth.org — AFAuth service directory

> The canonical opt-in directory of services that have announced
> support for AFAuth (Agent-First Auth). Each listing represents a
> service whose discovery host has cryptographically proven control of
> a `service_did`. Membership is voluntary and informational; the
> directory is non-normative and conforming AFAuth agents and services
> are not required to interact with it.

## Sibling sites (AFAuth constellation)

AFAuth is documented across three coordinated properties. This site is
the **data plane**. For the protocol itself and the developer
documentation, follow the links below.

- **Protocol home**: https://afauth.org/llms.txt — what AFAuth is, the manifesto, install paths for the CLI and SDK.
- **Documentation**: https://docs.afauth.org/llms.txt — quickstarts, SDK reference, concepts, the §-by-§ spec walkthrough.
- **Service directory** (this site): https://registry.afauth.org/llms.txt — opt-in registry of AFAuth-enabled services, mirrorable and non-normative.

## About this site

This site implements the informational service-directory convention
from [spec/directory.md](https://github.com/AFAuthHQ/spec/blob/main/spec/directory.md)
and [AFAP-0003](https://github.com/AFAuthHQ/spec/blob/main/proposals/0003-service-directory.md).

## How agents use this directory

The intended consumer is an AI agent (or a tool an agent uses) that
wants to discover AFAuth-enabled services in the wild without
hard-coded URLs. Typical flow:

1. `GET /v1/listings` — paginated, JSON, supports `?search=`,
   `?tag=`, `?status=`, `?updated_since=`, opaque `?cursor=`.
2. `GET /v1/listings/{service_did}` — one listing, fully serialized,
   including the discovery document fetched from the service's
   `/.well-known/afauth`.
3. The agent then talks AFAuth directly to the service's
   `endpoints.accounts` (etc.) — the directory is *not* part of the
   protocol's hot path.

Reads are CORS-open and cache-friendly. The directory revalidates
discovery documents on a daily cron; listings that fail three
consecutive fetches transition to `stale` and after a grace period
to `deleted`.

## Endpoints

- [Browse (HTML)](https://registry.afauth.org/) — human-friendly index of current listings.
- [List API](https://registry.afauth.org/v1/listings) — paginated JSON, primary read endpoint.
- [Operator commitment](https://registry.afauth.org/operator) — who runs this directory and what they may / may not do.
- [Take-down policy](https://registry.afauth.org/policy) — moderation policy for the canonical directory.
- [Spec](https://github.com/AFAuthHQ/spec/blob/main/spec/directory.md) — normative directory convention.
- [AFAP-0003](https://github.com/AFAuthHQ/spec/blob/main/proposals/0003-service-directory.md) — design rationale.

## What a listing looks like

```json
{
  "service_did": "did:web:api.example.com",
  "discovery_url": "https://api.example.com/.well-known/afauth",
  "discovery_doc": {
    "afauth_version": "0.1",
    "endpoints": { "accounts": "/v1/accounts", "owner_invitation": "/v1/owner-invitations", "claim_page": "/claim", "claim_completion": "/v1/claim/complete" },
    "features": ["key_rotation"],
    "recipient_types": ["email"],
    "signature_algorithms": ["ed25519"]
  },
  "status": "active",
  "tags": ["search", "media"],
  "first_listed_at": "2026-01-15T10:00:00Z",
  "fetched_at": "2026-05-25T06:00:00Z",
  "updated_at": "2026-05-25T06:00:00Z"
}
```

## Federation

This is the *canonical* directory but not the *only* directory. Anyone
may host a directory implementing the same surface — see
[§8 federation](https://github.com/AFAuthHQ/spec/blob/main/spec/directory.md#8-federation).
A consumer may aggregate across multiple directories or run a private
one.

## Contact

- Operational contact: [email protected]
- GitHub: https://github.com/AFAuthHQ/registry
- License: Apache-2.0 (code), CC-BY-4.0 (spec)