# photoproof.io auth.md

How AI agents authenticate with photoproof.io. photoproof.io has two surfaces for AI agents: a public read-only API that needs no credentials, and an MCP server that acts for one photographer with their OAuth consent.

## Discover

- Public API description: https://photoproof.io/openapi.json
- MCP server: https://photoproof.io/mcp (Streamable HTTP). Calling it without a token answers 401 with `WWW-Authenticate: Bearer resource_metadata="https://photoproof.io/.well-known/oauth-protected-resource/mcp"`.
- Protected-resource metadata (RFC 9728): https://photoproof.io/.well-known/oauth-protected-resource/mcp (the only OAuth-protected resource is https://photoproof.io/mcp; there is no root-level protected resource)
- Authorization server metadata (RFC 8414): https://photoproof.io/.well-known/oauth-authorization-server

## Pick a method

- Reading public data (plans and prices, public pages, site search, health): no auth. Call the endpoints in the OpenAPI description directly. They return no personal data.
- Working with a photographer's galleries and client picks: OAuth 2.1 authorization code flow with PKCE (S256) against the MCP server. There are no API keys.

## Register

Register your client with dynamic client registration (RFC 7591): POST https://photoproof.io/oauth/register with your `client_name` and `redirect_uris`. Public clients use `token_endpoint_auth_method: "none"`; confidential clients can use `client_secret_basic` or `client_secret_post`.

## Claim

photoproof.io does not offer agent self-registration (no anonymous, identity-assertion or service accounts for agents) and agents can't create photoproof.io accounts, so there is no separate claim step. Send the photographer to https://photoproof.io/oauth/authorize with `response_type=code`, your `client_id`, `redirect_uri`, `scope`, `state` and a PKCE `code_challenge` (S256). They sign in to photoproof.io (email and password, or Google) and click Allow.

Scopes:

- `galleries:read`: read the account, galleries, client selections and comments, recent activity and delivery links.
- `galleries:write`: also create new, empty galleries.

## Exchange

POST https://photoproof.io/oauth/token with `grant_type=authorization_code`, the `code`, your `redirect_uri`, `client_id` and the PKCE `code_verifier`. Access tokens last one hour. Renew with `grant_type=refresh_token`.

## Use credential

Send `Authorization: Bearer <access token>` on every request to https://photoproof.io/mcp.

## Errors

- 401 with `WWW-Authenticate: Bearer error="invalid_token"`: the token is missing, expired or revoked. Refresh it, or run the authorization flow again.
- A tool result marked as an error explains what went wrong in plain words, for example a read-only connection trying to create a gallery, or a usage limit (120 requests an hour, 20 new galleries a day).
- Public API errors are JSON: `{"error": "<code>", "message": "...", "docs": "https://photoproof.io/openapi.json"}`.

## Revocation

Revoke a token at https://photoproof.io/oauth/token (the `revocation_endpoint` in the authorization server metadata, RFC 7009). The photographer can also disconnect any app under Dashboard → Connected AI apps; the app loses access within a minute.

Agents can't pay, delete anything, upload photos or email clients. Human setup guide: https://photoproof.io/connect-ai. Questions: support@photoproof.io.
