# Agent authentication on Open Media

How an agent gets access to Open Media, and exactly which credentials exist. This file lives at `/auth.md`, the discovery path from the WorkOS auth.md spec. Open Media implements its anonymous registration; this file says plainly what it does not implement.

## Discover

- Public data needs no credential at all: `https://convo-mail-sync.convo-mail-sync.workers.dev/open/mcp`, `GET /v1/feed`, `GET /v1/search`, `GET /v1/posts`, `GET /v1/profiles/{handle}`, `GET /v1/events/upcoming` and every discovery file.
- Protected-resource metadata (RFC 9728): [https://convo-mail-sync.convo-mail-sync.workers.dev/.well-known/oauth-protected-resource](https://convo-mail-sync.convo-mail-sync.workers.dev/.well-known/oauth-protected-resource).
- Authorization-server metadata (RFC 8414), including the `agent_auth` block with `identity_endpoint` and `identity_types_supported`: [https://convo-mail-sync.convo-mail-sync.workers.dev/.well-known/oauth-authorization-server](https://convo-mail-sync.convo-mail-sync.workers.dev/.well-known/oauth-authorization-server).
- A protected route called without a valid credential returns 401 with `WWW-Authenticate: Bearer resource_metadata="https://convo-mail-sync.convo-mail-sync.workers.dev/.well-known/oauth-protected-resource"`.

## Pick a method

- **No credential:** everything public. Start here.
- **Anonymous agent registration** (`agent_auth`, type `anonymous`): an agent gets its own identity and an access token with the `public:read` scope, so its requests are counted in its own rate-limit bucket instead of sharing one with its IP address. It never grants access to anyone's account.
- **Sign in with Open Media (OAuth 2.1, for MCP hosts):** connect `https://convo-mail-sync.convo-mail-sync.workers.dev/account/mcp`. The host discovers `https://convo-mail-sync.convo-mail-sync.workers.dev/.well-known/oauth-protected-resource`, registers itself (client ID metadata document, or dynamic registration) and sends the person to `https://convo-mail-sync.convo-mail-sync.workers.dev/authorize`, where they enter their email, the code Open Media emails them, and approve. The host never sees their session; refreshing its token renews it.
- **Sign the person in with an email code (bearer):** for the account API (`/v1/me/...`) and the account MCP server (`/me/mcp`). Open Media emails the person a code from security@openmedia.site; they tell you the code; you get their access token. See "Sign a person in" below. People can also copy a token from the app (Settings, then Developers and agents). Either way it acts only as them.
- **OAuth 2.1 with PKCE (S256):** Open Media Events at `https://convo-mail-sync.convo-mail-sync.workers.dev/mcp`, scopes `events:read` and `events:write`, with client ID metadata documents or Dynamic Client Registration at `https://convo-mail-sync.convo-mail-sync.workers.dev/oauth/register`.

## Sign a person in

Works for existing accounts and creates new ones. Nothing happens without the code from the person's inbox.

```
POST https://convo-mail-sync.convo-mail-sync.workers.dev/v1/auth/email-code
Content-Type: application/json

{"email": "person@example.com"}
```

Tell the person a code is on its way, ask them for it, then:

```
POST https://convo-mail-sync.convo-mail-sync.workers.dev/v1/auth/verify
Content-Type: application/json

{"email": "person@example.com", "code": "12345678"}
```

The response holds `access_token` (send it as `Authorization: Bearer …`; it lasts `expires_in` seconds, an hour), `refresh_token` and `user`. Renew with `POST https://convo-mail-sync.convo-mail-sync.workers.dev/v1/auth/refresh` and `{"refresh_token": "…"}`; end the session with `POST https://convo-mail-sync.convo-mail-sync.workers.dev/v1/auth/sign-out`. A new account has no profile yet (`GET /v1/me` answers `no_profile`): ask the person for a name and handle and send them to `PUT https://convo-mail-sync.convo-mail-sync.workers.dev/v1/me/profile` as `{"displayName": "…", "handle": "…"}`. The same steps are MCP tools on `https://convo-mail-sync.convo-mail-sync.workers.dev/open/mcp` (`request_sign_in_code`, `sign_in_with_code`, `refresh_sign_in`) and `set_up_profile` on `/me/mcp`; the CLI does it with `open-media login you@example.com` (plain `open-media login` signs in through the browser instead). Keep both tokens private, as you would a password. Errors: `invalid_code` (400, ask for a new code), `rate_limited` (429 with `Retry-After`).

## Register an agent identity

```
POST https://convo-mail-sync.convo-mail-sync.workers.dev/agent/identity
Content-Type: application/json

{"type": "anonymous", "name": "my-agent"}
```

The response holds `registration_id`, `identity_assertion` (valid for 30 days), `assertion_expires`, `pre_claim_scopes` (`public:read`) and `post_claim_scopes` (empty). Only the `anonymous` type is supported: `service_auth` and `identity_assertion` (ID-JAG) registration return `unsupported_identity_type`.

## Claim

There is no claim ceremony and no `claim_endpoint`: an anonymous agent identity is never linked to a person. To act for a person, sign them in with an email code (above).

## Exchange

```
POST https://convo-mail-sync.convo-mail-sync.workers.dev/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&assertion=<identity_assertion>
```

The response is `{"access_token": "…", "token_type": "Bearer", "expires_in": 3600, "scope": "public:read"}`. Exchange the same assertion again when the access token expires. OAuth clients for Open Media Events exchange authorization codes and refresh tokens at the same endpoint.

## Use the access_token

```
Authorization: Bearer <access_token>
```

Agent tokens work on every public route and the public MCP server. Account routes need the person's own token and answer 401 to an agent token.

## Errors

- `400 invalid_grant`: the identity assertion is invalid or expired. Register again.
- `400 unsupported_identity_type`: only `{"type": "anonymous"}` is accepted.
- `401 unauthorized` with `WWW-Authenticate`: missing, expired or invalid token on a protected route.
- `429 rate_limited` with `Retry-After`: back off for the stated seconds.

## Revocation

Agent identity assertions expire after 30 days and access tokens after an hour; there is no `events_endpoint` for revocation events. Account tokens end when they expire or the person signs out. OAuth tokens for Open Media Events are revoked at `https://convo-mail-sync.convo-mail-sync.workers.dev/oauth/token`, the advertised revocation endpoint.
