# auth.md

Agent authentication for **404 Mates** publication APIs (MCP + REST).

## Audience

AI agents and Custom GPT / Claude connectors that create, update, or publish articles on `https://404mates.ai`.

## Registration / provisioning

There is **no self-serve OAuth registration**. Credentials are provisioned out-of-band:

1. Site operator generates `MATES_API_KEY` (e.g. `openssl rand -hex 32`)
2. Key is stored in Vercel env `MATES_API_KEY`
3. Operator shares the key with the agent host (Claude Connectors headers, ChatGPT Actions API key, Cursor MCP headers)

Revocation = rotate/remove `MATES_API_KEY` and redeploy.

## Methods supported

| Method | How |
|--------|-----|
| HTTP Bearer | `Authorization: Bearer <MATES_API_KEY>` |
| API key header | `x-api-key: <MATES_API_KEY>` |

Scopes (logical): `mates:publish` — create / update / publish articles.

## Discovery documents

- API Catalog: `https://404mates.ai/.well-known/api-catalog`
- OpenAPI: `https://404mates.ai/.well-known/openapi.json`
- MCP Server Card: `https://404mates.ai/.well-known/mcp/server-card.json`
- MCP manifest: `https://404mates.ai/.well-known/mcp.json`
- ARD catalog: `https://404mates.ai/.well-known/ai-catalog.json`
- Developer portal: `https://404mates.ai/developers`
- Agent instructions: `https://404mates.ai/llms.txt`
- MCP endpoint: `https://404mates.ai/api/mcp` (alias `/api/v1/mcp`)

## Errors

Failed requests return JSON with a string `error` message plus optional `code` and `hint` fields (legacy clients can keep reading `error` as a string).

## Why no OAuth metadata

404 Mates publication uses a **shared site API key**, not end-user OAuth/OIDC. Publishing fake `/.well-known/openid-configuration` would mislead agents. Prefer this `auth.md` + OpenAPI `securitySchemes.BearerAuth`.