# auth.md — BeYourCover

> How an AI agent obtains and uses a credential for the BeYourCover APIs.
> This document follows the auth.md convention (https://github.com/workos/auth.md).
> Everything below is public discovery information. Nothing here creates an
> account, sends mail, or issues a credential — it is safe to fetch.

## Who this is for

AI agents and MCP clients acting on behalf of an author, publisher or design
agency who already holds — or is willing to buy — a BeYourCover API plan. The
service generates book cover artwork: ebook covers, print wrap covers with a
KDP-ready PDF, and audiobook covers.

If you are a human, read https://beyourcover.com/api-docs instead.

## Resources

| Resource | URL | Accepts |
| --- | --- | --- |
| REST API | `https://beyourcover.com/api/v1` | Partner API key |
| MCP server | `https://beyourcover.com/api/mcp/mcp` | Partner API key **or** OAuth 2.1 access token |
| Liveness probe | `https://beyourcover.com/api/v1/health` | No credential |

## Discovery

| Document | URL |
| --- | --- |
| Protected resource metadata (RFC 9728) | `https://beyourcover.com/.well-known/oauth-protected-resource` |
| Authorization server metadata (RFC 8414) | `https://ufzzwcvuuodumlexxhfv.supabase.co/auth/v1/.well-known/oauth-authorization-server` |
| Authorization server metadata (same-origin mirror) | `https://beyourcover.com/.well-known/oauth-authorization-server` |
| API catalog (RFC 9727) | `https://beyourcover.com/.well-known/api-catalog` |
| OpenAPI 3.1 spec | `https://beyourcover.com/openapi.json` |
| MCP registry manifest | `https://beyourcover.com/server.json` |
| Site map for LLMs | `https://beyourcover.com/llms.txt` |

The authorization server is `https://ufzzwcvuuodumlexxhfv.supabase.co/auth/v1`. That issuer is what
`/.well-known/oauth-protected-resource` advertises in `authorization_servers`,
and it matches the `issuer` in the authorization server's own metadata. The
same-origin mirror serves that document verbatim for clients that probe this
origin instead of the issuer's; the `issuer` inside is still `https://ufzzwcvuuodumlexxhfv.supabase.co/auth/v1`.

## Registration methods

Two credentials exist. Only the first can be obtained by an agent unattended.

### 1. OAuth 2.1 authorization code + PKCE — MCP endpoint only

Fully self-service, including client registration.

1. `GET https://beyourcover.com/.well-known/oauth-protected-resource` → read `authorization_servers[0]`.
2. `GET https://ufzzwcvuuodumlexxhfv.supabase.co/auth/v1/.well-known/oauth-authorization-server` → read the endpoints.
3. Register a client at the `registration_endpoint` (RFC 7591 dynamic client
   registration). It is open — no pre-shared credential is required.
4. Run the authorization code flow with PKCE (`code_challenge_methods_supported`
   includes `S256`), requesting `scope=openid email offline_access`.
5. Exchange the code at the `token_endpoint` for an access token.

The access token is a JWT signed by the project's keys and is verified here
against `https://ufzzwcvuuodumlexxhfv.supabase.co/auth/v1/.well-known/jwks.json`.

**A token alone is not access.** The authenticated account must also have an
active BeYourCover API plan; the account may hold it directly or through a team
seat. Without one, the MCP endpoint answers `401` even for a perfectly valid
token. This is the expected outcome for a brand-new account — it is a
subscription check, not a bug in the flow.

### 2. Partner API key — REST and MCP

Format `byc_sk_` followed by 32 hex characters. Works at both
`https://beyourcover.com/api/v1` and `https://beyourcover.com/api/mcp/mcp`.

Provisioning requires a signed-in human and cannot be automated by an agent:

1. Subscribe to an API plan at https://beyourcover.com/for-publishers (from
   $79/month for the Starter tier, 150 credits).
2. Create the key in the account dashboard at https://beyourcover.com/account-dashboard.
   It is shown once, at creation time.

If you have no key and no plan, hand https://beyourcover.com/for-publishers to your user.
Do not attempt to provision one programmatically — the key endpoint authenticates
with a browser session, not a bearer token, and will reject you.

## Using the credential

Send it in the `Authorization` header. This is the only accepted method — no
query parameter, no request-body field.

```http
Authorization: Bearer byc_sk_your_api_key_here
```

```bash
curl https://beyourcover.com/api/v1/books \
  -H "Authorization: Bearer byc_sk_your_api_key_here"
```

For MCP over Streamable HTTP:

```bash
claude mcp add --transport http beyourcover https://beyourcover.com/api/mcp/mcp \
  --header "Authorization: Bearer byc_sk_your_api_key_here"
```

A missing or invalid credential at the MCP endpoint returns `401` with a
`WWW-Authenticate` header pointing back at
`https://beyourcover.com/.well-known/oauth-protected-resource`, which restarts discovery.

## Scopes

`openid email offline_access` — requested at the authorization server. There are no
resource-specific scope values: what a credential may do is set by the account's
plan, not by the scope string. Per-operation credit costs and genre coverage are
readable at `GET https://beyourcover.com/api/v1/capabilities` once authenticated.

## Revocation

- **API key** — revoke it in the account dashboard; it stops working immediately.
- **OAuth token** — revoke at the authorization server, or cancel the plan. The
  subscription check runs on every request, so access ends when the plan does.

## Not implemented

This service does **not** implement the auth.md agent-registration endpoints.
There is no `POST /agent/auth`, no `/agent/identity`, no claim ceremony, and no
`agent_auth` block in authorization server metadata — the authorization server
is hosted by a third party, so that document is not ours to extend. Requests to
those paths will 404. Use one of the two methods above instead.