# Auth.md

**There's a Book in Everyone — Agent Authentication**

This document describes how AI agents authenticate with the APIs served under
`https://theresabookineveryone.com`. It follows the auth.md convention
(https://github.com/workos/auth.md).

## Site

- Site: `https://theresabookineveryone.com`
- Contact: `hello@theresabookineveryone.com`
- Terms: `https://theresabookineveryone.com/terms`
- Privacy: `https://theresabookineveryone.com/privacy`

## Authorization server

Authentication is delegated to a managed OpenID Connect / OAuth 2.0
authorization server. Discovery documents are mirrored at this origin as
302 redirects to the canonical issuer:

- OpenID Connect discovery: `https://theresabookineveryone.com/.well-known/openid-configuration`
- OAuth 2.0 authorization-server metadata: `https://theresabookineveryone.com/.well-known/oauth-authorization-server`
- Protected-resource metadata: `https://theresabookineveryone.com/.well-known/oauth-protected-resource`
- API catalog (RFC 9727): `https://theresabookineveryone.com/.well-known/api-catalog`

All endpoints (`authorization_endpoint`, `token_endpoint`, `jwks_uri`,
`registration_endpoint`, `revocation_endpoint`) are exposed through the
discovery documents above. Fetch discovery to obtain the current URLs; do not
hardcode them.

## Registration

- **Dynamic Client Registration (RFC 7591)** is enabled. Agents SHOULD register
  a client automatically by POSTing to the `registration_endpoint` returned in
  `/.well-known/oauth-authorization-server`.
- **Manual registration** is available on request — email
  `hello@theresabookineveryone.com` with the agent name, publisher, redirect
  URIs, and intended scopes.

## Identity types

- `human` — an end user signing in through the hosted consent page.
- `agent-on-behalf-of-human` — an autonomous agent acting on behalf of a
  signed-in end user. Consent is obtained through the standard OAuth
  authorization-code flow with PKCE.

Machine-to-machine (`client_credentials`) access is not currently offered.

## Credential types

- `oauth2-bearer-jwt` — access tokens issued by the authorization server,
  presented as `Authorization: Bearer <token>` on every request.
- `oidc-id-token` — ID tokens returned alongside access tokens for identity
  verification.

Tokens are short-lived. Use the returned `refresh_token` and the
`token_endpoint` to obtain new access tokens; do not re-run the authorization
flow per request.

## Scopes

Request the minimum useful set. Standard identity scopes are supported:

- `openid` — required for OpenID Connect.
- `email` — end-user email address.
- `profile` — basic profile information.

App-level data permissions are enforced by the resource server and its
backend policies, not by additional OAuth scopes.

## Protected resources

- Model Context Protocol endpoint: `https://theresabookineveryone.com/mcp`

All protected requests MUST include `Authorization: Bearer <access_token>`.
Unauthenticated requests receive `401 Unauthorized` with a
`WWW-Authenticate: Bearer resource_metadata="…/.well-known/oauth-protected-resource"`
challenge.

## Revocation and claims

- Token revocation: use `revocation_endpoint` from
  `/.well-known/oauth-authorization-server`.
- Account or agent-access complaints: email
  `hello@theresabookineveryone.com`. Include the `client_id`, approximate
  time, and the affected user identifier.

## Rate limits and abuse

- Fair-use rate limits apply per client and per user. Excessive traffic is
  throttled with `429 Too Many Requests`; back off and retry with jitter.
- Do not scrape authenticated data on behalf of users who have not granted
  consent.
- Report vulnerabilities to `hello@theresabookineveryone.com`.

## Change log

- 2026-07-29 — Renamed top-level heading to `Auth.md` for spec compliance.
- 2026-07-29 — Initial publication.