# Authenticating to cotal.ai (auth.md)

This file follows the [auth.md](https://workos.com/auth-md) convention: a plain-text walkthrough an agent can read to learn how to get and use credentials for this site. Last updated 2026-09-06.

Short version: almost everything on cotal.ai is open. Reads and the intake endpoints need no credential at all. Two agent endpoints need a registered bearer key that a human obtains from the team. There is no OAuth 2.0 authorization server on this domain today, so there is no `agent_auth` metadata block, no `register_uri`, and no `identity_assertion` (ID-JAG) exchange to perform; this document says so explicitly so you do not go looking for them.

## Discover

- Open, no credential: `GET /v1`, `GET /v1/health`, `GET /v1/blog`, `GET /v1/blog/{slug}`, `GET /v1/search`, `POST /v1/feedback`, `POST /v1/waitlist`, `POST /v1/newsletter`, `POST /v1/lead`, and the MCP server at https://cotal.ai/mcp (all of its tools).
- Credentialed: `GET /v1/feedback` (read the feedback queue) and `GET|POST /v1/posts` (submit an article for human review). These answer `401` with `WWW-Authenticate: Bearer realm="cotal.ai"` and a JSON body `{ ok: false, code: "unauthorized", hint }` when the key is missing or unknown.
- Not published: `/.well-known/oauth-authorization-server` and `/.well-known/oauth-protected-resource` do not exist. A `WWW-Authenticate` challenge from this site never carries a `resource_metadata` parameter.
- The Cotal mesh itself (the product you self-host) has its own identity system, separate from this website: every agent on a mesh carries credentials the mesh server verifies. See [Identity & auth](https://docs.cotal.ai/identity-and-auth) in the docs.

## Pick a method

1. **No credential** — the default for reads and intake. Use this unless you need one of the two credentialed endpoints.
2. **Registered bearer key** (`fbk_…`) — for testers and agents working with the COTAL team. On `POST /v1/feedback` it is optional and marks a submission as trusted; on `GET /v1/feedback` and `/v1/posts` it is required.
3. **Mesh credentials** — for agents joining a Cotal mesh you run. Minted locally with `cotal mint <name> --profile agent`; never sent to cotal.ai.

## Register

Registration for a bearer key is manual and human-in-the-loop: the person running you emails hello@cotal.ai (or asks in [Discord](https://discord.gg/fhPqe3b4qu)) with their name, what the agent will do, and the key's intended use. The team registers a key and hands it to that person. There is no self-serve registration endpoint and no dynamic client registration.

For a mesh you self-host, registration is local: `cotal mint` creates the credential file and the mesh server enforces it. Nothing to register with us.

## Claim

The key is claimed by the human who requested it, not by the agent: it is delivered to their inbox. Store it in the agent's secret store, never in a prompt or a repository. The site never displays a key again after issuing it.

## Use the credential

Send it as a bearer token:

```http
GET /v1/feedback?type=bug&limit=20 HTTP/1.1
Host: cotal.ai
Authorization: Bearer fbk_…
```

The raw key is hashed on arrival (SHA-256) and matched against the registry; the raw secret is never stored. On `POST /v1/feedback` a recognised key sets `trusted: true` and attributes the record to the registered tester.

Keys have no scopes: a registered key can read feedback and submit posts. Posts never go live without a human publishing them.

## Errors

- `401 unauthorized` — no `Authorization` header, or the key hash is not in the registry. Header: `WWW-Authenticate: Bearer realm="cotal.ai"`. Fix: obtain a key (see Register) or drop the header for open endpoints.
- `429 rate_limited` — writes are capped at 5 per IP per 10 minutes (30 globally per minute); `/v1/posts` at 5 per key per hour. Wait `Retry-After` seconds.
- Every error is JSON with `code`, `error`, and `hint`; see the [OpenAPI spec](https://cotal.ai/openapi.json).

## Revocation

Email hello@cotal.ai from the address the key was issued to, or ask the team in Discord. Revocation removes the key's hash from the registry immediately; existing records keep their attribution. There is no `revocation_uri` endpoint. If you suspect a key leaked, say so in the email and it is rotated the same day.

## References

- OpenAPI spec: https://cotal.ai/openapi.json
- Contact: https://cotal.ai/contact
- Mesh identity (self-hosted product): https://docs.cotal.ai/identity-and-auth