# auth.md — World Aid Network agent authentication

World Aid Network publishes a **public, read-only agent surface**. Reading site
content, Markdown mirrors, open datasets and MCP tools **needs no
authentication**. Optional OAuth client registration is available for agents
that want a client identity; it does not unlock private data today.

| Field | Value |
|---|---|
| Issuer | `https://worldaidnetwork.org` |
| Protected resource | `https://worldaidnetwork.org` |
| Identity types supported | `software_agent`, `anonymous` |
| Credential types supported | `client_secret` |
| Anonymous access | Supported for all published read paths and MCP tools |
| `register_uri` | `https://worldaidnetwork.org/oauth/register` |

## Step 1 — Discover

Fetch the two metadata documents. Everything else is derived from them; do not
hard-code endpoints.

```http
GET https://worldaidnetwork.org/.well-known/oauth-authorization-server
GET https://worldaidnetwork.org/.well-known/oauth-protected-resource
```

The authorization-server document returns `issuer`, `token_endpoint`,
`authorization_endpoint`, `registration_endpoint`, `jwks_uri`,
`grant_types_supported` and an `agent_auth` block (including
`anonymous_access`). The protected-resource document returns the resource
identifier, its `authorization_servers`, `scopes_supported` and
`bearer_methods_supported`.

A future `401` from a protected path will carry:

```
WWW-Authenticate: Bearer realm="World Aid Network",
  resource_metadata="https://worldaidnetwork.org/.well-known/oauth-protected-resource"
```

Today, MCP tools and public content do not return `401`.

## Step 2 — Register (optional)

Dynamic client registration (RFC 7591) is open and immediate — there is no
approval queue. **Skip this step for anonymous read access.**

```http
POST https://worldaidnetwork.org/oauth/register
Content-Type: application/json

{ "client_name": "My research agent", "redirect_uris": [] }
```

Returns `client_id` and `client_secret`. Send an empty `redirect_uris` for
machine-to-machine use. Store both values — the secret is not recoverable.

## Step 3 — Claim

Not applicable for public programme data. There is no agent-level identity
claim; registered clients are pseudonymous.

## Step 4 — Exchange credentials for a token (optional)

Machine-to-machine:

```http
POST https://worldaidnetwork.org/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id=...&client_secret=...&scope=wan:read
```

Or authorization-code with PKCE (`S256`) via
`https://worldaidnetwork.org/oauth/authorize`. Public MCP tool calls do not
require the resulting bearer token.

## Step 5 — Use

```http
POST https://worldaidnetwork.org/mcp
Content-Type: application/json

{"jsonrpc":"2.0","id":1,"method":"tools/list"}
```

No `Authorization` header is required. Optionally send
`Authorization: Bearer <access_token>` once tokens are issued — tools remain
read-only either way.

## Step 6 — Revoke

Tokens are short-lived. Discard credentials at end of use. To retire a client,
discard `client_id` / `client_secret`. Contact info@worldaidnetwork.org if a
secret leaks.

## Other agent surfaces

- MCP: `https://worldaidnetwork.org/mcp` — card at `/.well-known/mcp/server-card.json`
- A2A: `https://worldaidnetwork.org/a2a` — card at `/.well-known/agent-card.json`
- Skills: `/.well-known/agent-skills/index.json`
- Site map for LLMs: `/llms.txt`
- Markdown negotiation: send `Accept: text/markdown` on any content URL

## Rate limits

Anonymous access may be rate-limited at the edge for abuse protection. There is
no paid higher-limit API today.

## Contact

Questions about agent access: info@worldaidnetwork.org