# PodHood agent authentication

> Short version: reading published content needs no credentials — each channel's MCP server and Markdown pages are anonymous. The creator API (`/api/v1` + the creator MCP) requires a credential resolving to a channel member: an API key a human creates in Studio, or an OAuth sign-in run from an MCP client. It reads that member's own channels in full.

## Discover

The anonymous surface is each channel's MCP server at `https://<channel>.podhood.com/mcp` (Streamable HTTP) plus the `.md` page companions — no RFC 9728 protected-resource metadata, nothing to negotiate: published episodes are world-readable by design. The credential-gated creator API has two transports: the REST endpoints described by the [OpenAPI spec](https://podhood.com/openapi.json) (base path `/api/v1`) and the creator MCP at `https://podhood.com/mcp`. The creator surface is a full OAuth 2.1 protected resource: any 401 carries a `WWW-Authenticate` challenge pointing at RFC 9728 protected-resource metadata (`/.well-known/oauth-protected-resource/mcp`, also served at the root fallback), which names the authorization server (RFC 8414 metadata, dynamic client registration per RFC 7591, PKCE S256, `resource` per RFC 8707, refresh tokens via `offline_access`).

## Pick a method

For reading **published** content, use **anonymous MCP** — plain requests, no Authorization header; an unknown or unpublished resource is a JSON 404, indistinguishable from nonexistence. For programmatic access to **your own channels** (drafts included), use the **creator API** — with an API key for scripts, or by OAuth sign-in when connecting from an interactive MCP client. (Undocumented session-gated routes exist under /api for the product’s own UI; they are not part of this contract.)

## Register / Claim

Agents cannot silently self-provision access: every path runs through a human. For keys, a human member of the channel creates one in **Studio → Settings → API keys** (available on paid plans) and hands it to the tool or agent that needs it. For OAuth, an MCP client may self-register as a public client (RFC 7591, unauthenticated), but tokens are only minted after the human signs in and approves the `creator:read` consent in their browser.

## Use the credential

Send the key in the `x-api-key` header (or as a Bearer token — the `podhood_` prefix routes it) on every REST call, and the same way when connecting the creator MCP at `https://podhood.com/mcp`. An OAuth access token is a plain `Authorization: Bearer` on the same endpoints:

```sh
curl -H "x-api-key: $PODHOOD_API_KEY" "https://podhood.com/api/v1/channels"
```

## Errors

Errors are always JSON of the shape `{ "error": "message" }` — never HTML. A missing or invalid credential is a 401 carrying a `WWW-Authenticate` challenge that points at the OAuth discovery metadata; a credential on a channel whose owner is on the Free plan is a 403; a channel the caller is not a member of is a 404, indistinguishable from nonexistence; an exhausted per-key rate limit is a 429.

## Revocation

Revoke a key any time in Studio → Settings → API keys — immediate on the next request. OAuth access tokens expire within an hour and renew only by refresh token; disconnecting the client stops renewal. A creator unpublishing an episode removes it from every anonymous surface (pages, search, MCP) at once.

## Related

- [Developer & agent guide](https://podhood.com/developers)
- [OpenAPI spec](https://podhood.com/openapi.json)