# auth.md

Agent authentication for PeppolNews.

> Walkthrough of how AI agents should obtain credentials for PeppolNews.
> Spec reference: https://workos.com/auth-md

## Discover

Resource server: `https://peppolnews.com`

Discovery surfaces:

- **Protected Resource Metadata (RFC 9728)** — `https://peppolnews.com/.well-known/oauth-protected-resource`
- **Authorization Server Metadata (RFC 8414)** — `https://peppolnews.com/.well-known/oauth-authorization-server`
- **Agent Auth (agent_auth)** — declared inside the AS metadata
- **Web Bot Auth directory (RFC 9421)** — `https://peppolnews.com/.well-known/http-message-signatures-directory`
- **WWW-Authenticate hint** — every protected `/api/v1/*` endpoint that requires auth returns
  `401` with `WWW-Authenticate: Bearer resource_metadata="https://peppolnews.com/.well-known/oauth-protected-resource"`.

## Pick a method

PeppolNews supports three identity types for agents:

| Method                 | identity_type        | Use when                                          |
|------------------------|----------------------|---------------------------------------------------|
| Anonymous              | `anonymous`          | Read-only access (default — no credential needed) |
| Identity assertion     | `identity_assertion` | Write-surface access (webhooks, future POST APIs) |
| HTTP message signature | (RFC 9421)           | Bot identification without bearer tokens          |

The read API is open. Use `identity_assertion` only when you need a write
endpoint such as `/api/v1/webhooks`.

## Register

`agent_auth.register_uri`: `https://peppolnews.com/api/v1/agent-auth/register`

POST a JSON body shaped:

```json
{
  "client_name": "Acme Agent",
  "contact": "ops@acme.example",
  "identity_type": "identity_assertion",
  "assertion_types_supported": ["urn:ietf:params:oauth:token-type:id-jag"]
}
```

Response:

```json
{
  "client_id": "string",
  "registration_access_token": "string",
  "claim_uri": "https://peppolnews.com/api/v1/agent-auth/claim",
  "revocation_uri": "https://peppolnews.com/api/v1/agent-auth/revoke"
}
```

## Claim

`agent_auth.claim_uri`: `https://peppolnews.com/api/v1/agent-auth/claim`

Exchange your registration token for a short-lived access token. Send the
identity assertion (`id-jag` per the spec enum) in the request body. The
response carries a Bearer token scoped to the surfaces you registered for.

## Use the credential

Attach `Authorization: Bearer <token>` to protected requests. Read endpoints
(GET) accept anonymous traffic and ignore the header.

For HTTP message signatures, sign requests per RFC 9421 using a key listed in
`https://peppolnews.com/.well-known/http-message-signatures-directory`. The signature
covers `@method`, `@target-uri`, `@authority`, and `content-digest`.

## Errors

| Status | Code              | Meaning                                  |
|--------|-------------------|------------------------------------------|
| 401    | `unauthorized`    | Missing/invalid bearer or signature      |
| 403    | `forbidden`       | Token does not cover the requested scope |
| 404    | `not_found`       | Resource path unknown                    |
| 429    | `rate_limited`    | Edge throttle hit                        |
| 500    | `internal`        | Server-side fault                        |

All errors are JSON (`Content-Type: application/json`) shaped:

```json
{ "error": { "code": "unauthorized", "message": "string", "hint": "string?" } }
```

Unauthenticated requests to protected endpoints also include:

```
WWW-Authenticate: Bearer realm="peppolnews", resource_metadata="https://peppolnews.com/.well-known/oauth-protected-resource"
```

## Revocation

`agent_auth.revocation_uri`: `https://peppolnews.com/api/v1/agent-auth/revoke`

POST your token (RFC 7009 shape):

```json
{ "token": "string", "token_type_hint": "access_token" }
```

Returns `200` with empty body on success. Token cannot be reused after this.

## References

- WorkOS auth.md draft: https://workos.com/auth-md
- RFC 9728 (OAuth Protected Resource Metadata)
- RFC 8414 (OAuth Authorization Server Metadata)
- RFC 9421 (HTTP Message Signatures)
- RFC 7009 (OAuth Token Revocation)
- Agent Auth identity_assertion / id-jag — see WorkOS spec for the enum.