# auth.md — Agent Authentication for anselmfowel.com

This document describes how AI agents authenticate with the APIs published by
**https://anselmfowel.com**. It follows the [auth.md](https://github.com/workos/auth.md)
convention and complements the machine-readable metadata at:

- [`/.well-known/oauth-authorization-server`](https://anselmfowel.com/.well-known/oauth-authorization-server)
- [`/.well-known/oauth-protected-resource`](https://anselmfowel.com/.well-known/oauth-protected-resource)
- [`/.well-known/openid-configuration`](https://anselmfowel.com/.well-known/openid-configuration)
- [`/.well-known/api-catalog`](https://anselmfowel.com/.well-known/api-catalog)
- [`/.well-known/agent-skills/index.json`](https://anselmfowel.com/.well-known/agent-skills/index.json)
- [`/.well-known/mcp/server-card.json`](https://anselmfowel.com/.well-known/mcp/server-card.json)

## MCP tools (no OAuth required)

The MCP server at [`https://anselmfowel.com/api/mcp`](https://anselmfowel.com/api/mcp) (see the server
card above) exposes the public AI Prompt Library. Its `auth.type` is
`none` — `list_prompt_categories` and `search_prompts` need no
credentials at all, and `get_prompt` takes an email address directly as
a tool argument instead of a bearer token (subscribing it to the
newsletter on first use, the same free-to-browse, email-to-unlock model
as the website). The OAuth flow below applies only to the separate,
still-unimplemented blog/contact/newsletter agent endpoints.

## Registration

Agents register via Dynamic Client Registration (RFC 7591):

```
POST https://anselmfowel.com/api/oauth/register
Content-Type: application/json

{
  "client_name": "My Agent",
  "grant_types": ["client_credentials", "authorization_code"],
  "scope": "agent:read agent:write",
  "identity_type": "agent"
}
```

Response:

```json
{
  "client_id": "…",
  "client_secret": "…",
  "registration_access_token": "…",
  "registration_client_uri": "https://anselmfowel.com/api/oauth/register/…"
}
```

## Identity types

| identity_type      | Meaning                                                    |
| ------------------ | ---------------------------------------------------------- |
| `agent`          | Autonomous agent acting on its own behalf.                 |
| `user-on-behalf` | Agent acting on behalf of a human end-user with consent.   |

## Credential types

- `dcr` — Dynamic Client Registration bearer token (recommended for agents).
- `client_secret` — Traditional OAuth 2.0 client secret.

## Token endpoint

```
POST https://anselmfowel.com/api/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
&client_id=…
&client_secret=…
&scope=agent:read agent:write
```

## Scopes

| Scope                    | Grants                                          |
| ------------------------ | ----------------------------------------------- |
| `agent:read`           | Read blog posts and public metadata.            |
| `agent:write`          | Invoke write tools (contact, newsletter).       |
| `newsletter:subscribe` | Subscribe an email to the newsletter.           |
| `contact:send`         | Post a message via the contact form.            |

## Claims

Retrievable via `GET https://anselmfowel.com/api/oauth/userinfo` with a bearer access token:

```json
{
  "sub": "agent_…",
  "client_id": "…",
  "identity_type": "agent",
  "scope": "agent:read agent:write"
}
```

## Revocation

```
POST https://anselmfowel.com/api/oauth/revoke
Content-Type: application/x-www-form-urlencoded

token=…
&token_type_hint=access_token
```

## Status

The OAuth endpoints listed here are provisioned as stubs that return
`501 Not Implemented` until a production identity provider (e.g. WorkOS or
Auth0) is wired in. The discovery documents already point at the target URLs
so agent runtimes that consume this metadata will work automatically once
those stubs are replaced with a real implementation.

## Contact

Questions about agent access: <contact@anselmfowel.com> or use the [contact
form](https://anselmfowel.com/contact).