# auth.md

## Audience and access

Agents can read the published catalogue, website pages and FAQ. Registration creates an anonymous client with only the `content:read` scope. It does not create a customer account or grant access to inquiries, contact details submitted through forms, moderation or administration.

Public HTML, Markdown and llms.txt can be read without credentials. OAuth is used for the JSON catalogue API.

## Discovery

- Resource metadata: https://pamyatniki34.ru/.well-known/oauth-protected-resource
- Authorization server: https://pamyatniki34.ru/.well-known/oauth-authorization-server
- API catalogue: https://pamyatniki34.ru/.well-known/api-catalog
- Documentation: https://pamyatniki34.ru/agent/api-docs.md

The protected resource identifier and token audience are `https://pamyatniki34.ru`. The `content:read` scope applies to the published JSON content API.

## Anonymous registration

Send `POST https://pamyatniki34.ru/agent/register` with `Content-Type: application/json` and the body `{"identity_type":"anonymous","scope":"content:read"}`.

The registration and claim endpoint is the same endpoint. A successful response is HTTP 201 and contains `client_id`, `client_secret`, `client_secret_expires_at`, the scope and supported grants. Credentials expire after 24 hours. Keep the secret private. Registration does not require an email or send messages.

## Get and use a token

Send `POST https://pamyatniki34.ru/oauth/token` using HTTP Basic authentication with the returned client ID and secret. Use a form body `grant_type=client_credentials&scope=content%3Aread` and `Content-Type: application/x-www-form-urlencoded`.

The access token lasts 900 seconds. Send it as `Authorization: Bearer ACCESS_TOKEN` to `GET https://pamyatniki34.ru/api/catalog` or `GET https://pamyatniki34.ru/api/catalog/pages?path=%2Fkatalog%2F`. Query parameter `q` searches page titles and descriptions. Tokens are RS256 signed; public verification keys are at https://pamyatniki34.ru/oauth/jwks.

## Authorization code

If a client needs the authorization-code flow, register up to three exact HTTPS `redirect_uris`. Request a code at https://pamyatniki34.ru/oauth/authorize with `response_type=code`, the client ID, exact redirect URI, `scope=content:read`, `state`, `code_challenge` and `code_challenge_method=S256`.

This flow represents the same anonymous client and grants access only to content already published on the website. It does not authenticate a person. Codes expire after 300 seconds and are consumed once. Exchange a code at the token endpoint using HTTP Basic client authentication, the exact redirect URI and the PKCE `code_verifier`. A failed code exchange requires a new authorization request. Refresh tokens are not issued.

## Revoke and limits

Revoke an access token with `POST https://pamyatniki34.ru/oauth/revoke`, HTTP Basic client authentication and a form body containing `token` and `token_type_hint=access_token`.

Registration and token endpoints are rate limited. HTTP 429 means retry later. Only anonymous registration is supported; verified-email and identity-assertion flows are not offered.

Passive discovery should read the documents above. Do not register clients or request tokens during a passive scan.