# Agent auth on PeppolCheck.fr

> How AI agents should authenticate to PeppolCheck.fr. Short answer: the current public API is unauthenticated. Long answer: the metadata below exists so that agents can probe consistently today and so that any future authenticated tier can be added without breaking discovery. Spec reference: https://workos.com/auth-md.

## Discover

Start at `https://peppolcheck.fr/.well-known/oauth-protected-resource` (RFC 9728 protected-resource metadata). The document advertises:

- `resource` — the resource server identifier.
- `authorization_servers` — list of authorization-server origins.
- `agent_auth` — the WorkOS auth.md `agent_auth` block describing the agent-auth flow.
- `scopes_supported`, `bearer_methods_supported`.

The `agent_auth` block on this resource describes `identity_types_supported = ["anonymous"]` because the public API is open. The `anonymous.credential_types_supported` field is `["none"]` — no credentials required; just call the API.

## Pick a method

For PeppolCheck.fr today there is only one path:

- **anonymous** — call the public API with no Authorization header. Identify yourself with a descriptive `User-Agent` so we can debug rate-limit issues.

When PeppolCheck.fr exposes authenticated endpoints (e.g. high-volume search or write surfaces), they will be advertised under `identity_types_supported` with `identity_assertion` blocks pointing at register/claim URIs.

## Register

Not required for anonymous use. Future register endpoint will be advertised as `agent_auth.register_uri`.

## Claim

Not applicable for anonymous use. Future claim endpoint will be advertised as `agent_auth.claim_uri`.

## Use the credential

For anonymous access:

```
GET /api/v1/participant/0208:0848934496 HTTP/1.1
Host: peppolcheck.fr
Accept: application/json
User-Agent: MyAgent/1.0 (+https://example.com/contact)
```

No Authorization header. No cookies. No CAPTCHA.

When authenticated endpoints exist, they will accept `Authorization: Bearer <token>` per RFC 6750, and the `WWW-Authenticate` challenge on 401 will be `Bearer resource_metadata="https://peppolcheck.fr/.well-known/oauth-protected-resource"`.

## Errors

All API errors are JSON:

```json
{ "error": { "code": "<machine_code>", "message": "<human readable>" } }
```

Agent-relevant codes:

- `invalid_participant_id` (400) — your Peppol ID is malformed. Fix the format `{4 digits}:{value}` and retry.
- `missing_query` / `query_too_short` (400) — provide `q` with at least 2 chars.
- `not_found` (404) — the participant is not registered on Peppol. Do not retry.
- `lookup_failed` / `search_failed` (502) — upstream OpenPeppol registry failed. Retry with exponential backoff.

## Revocation

There are no agent credentials to revoke at this time. Future `agent_auth.revocation_uri` will be published in the protected-resource metadata when authenticated endpoints are added.

## Related discovery

- `https://peppolcheck.fr/.well-known/oauth-protected-resource` — RFC 9728 metadata.
- `https://peppolcheck.fr/.well-known/oauth-authorization-server` — RFC 8414 metadata (currently advertises only anonymous flow).
- `https://peppolcheck.fr/.well-known/api-catalog` — RFC 9727 catalog pointing at OpenAPI.
- `https://peppolcheck.fr/openapi.json` — full API surface.
- `https://peppolcheck.fr/llms.txt` and `https://peppolcheck.fr/llms-full.txt` — agent manual.

For questions: willem@e-invoice.be.