# auth.md

How to authenticate against the Azurade AI API at `https://azurade.com`.

## What exists

- **API keys.** Send `Authorization: Bearer sk-...`; the same secret is also
  accepted in an `X-API-Key` header. The account holder creates and deletes
  keys on the profile page (`https://azurade.com/profile/`). The secret is shown once
  and stored hashed; afterwards the page lists only its name and a short
  prefix.
- **User session tokens.** PocketBase auth tokens in the `Authorization`
  header. This is what the web app uses. Accounts are created at
  `https://azurade.com/login/`.

- **OAuth 2.1 for MCP clients.** The MCP server at `https://azurade.com/mcp` answers
  401 with `resource_metadata` pointing at its protected resource metadata,
  https://azurade.com/.well-known/oauth-protected-resource/mcp (the whole API's is at
  https://azurade.com/.well-known/oauth-protected-resource). Authorization code with
  PKCE (S256) only. Clients identify themselves with a Client ID Metadata
  Document (an https `client_id`) or register at
  `https://azurade.com/api/oauth/register` (RFC 7591). A person signs in and approves
  the client on `https://azurade.com/oauth/authorize/`; the access token is an API key
  named after the client, so it works on `/api/v2` too. Tokens do not expire,
  so there are no refresh tokens.
- **Agent registration.** An agent that has no key asks for one with the
  person's email, and the person approves it in the browser (below).

A key inherits the account that created it: same credit balance, same prices,
same per-account visibility of generations. A key, and so an OAuth token, can
generate, upload inputs, use the prompt tools, read the balance and past
generations, and start a checkout for more credits, which only the person
completes by paying with a card; that is the API in the OpenAPI document. It
can revoke itself, and it cannot create or list keys, delete other keys, open
the billing portal, cancel a subscription, or edit or delete the account; those take the person's own
sign-in on the site. So deleting a key ends its access for good.

## What does not exist

No client credentials grant, no refresh tokens and no OpenID Connect. There is
one scope, `api`, which every key and token carries: the fixed reach
described above. Every key has a person behind it who signed in and approved
it; there is no anonymous registration (`anonymous_not_enabled`) and no
identity provider whose assertions are trusted (`issuer_not_enabled`).

## For agents

You are the intended reader if you are an AI agent or a script acting for a
person. If the person already gave you a key, send it as
`Authorization: Bearer sk-...` on every request and skip to step 5. An MCP
client that supports OAuth connects to `https://azurade.com/mcp` and lets the person
approve it in the browser instead. Otherwise, register:

1. `POST https://azurade.com/api/agent/register` with
   `{"type": "service_auth", "login_hint": "<the person's email>"}`
   (`Content-Type: application/json`). The answer carries `claim_token`
   (keep it to yourself) and `claim`: `user_code` (six digits),
   `verification_uri`, `expires_in` (900 seconds) and `interval` (5
   seconds).
2. Show the person the link and the code in one message: "Open this link,
   sign in as <email> (or sign up), and type this code: 123456." The code
   goes into the page, not back to you. Someone new signs up at the link like
   anyone else.
3. Every `interval` seconds, `POST https://azurade.com/api/oauth/token`
   (form-encoded) with
   `grant_type=urn:workos:agent-auth:grant-type:claim&claim_token=<claim_token>`.
   `authorization_pending` means keep polling; `access_denied` means the
   person declined; `expired_token` means the 15 minutes passed, the code
   was mistyped five times or the token was already used, so register again.
4. Success is `{"access_token": "sk-...", "token_type": "Bearer", "scope":
   "api"}`: an API key on the person's account, named "Agent" on their
   profile page. Store it; it does not expire.
5. Follow `https://azurade.com/.well-known/agent-skills/azurade-generation/SKILL.md` or
   the OpenAPI document at `https://azurade.com/api/v2/openapi.json` to estimate,
   generate and download. When a call answers `402 insufficient_credits`,
   `POST https://azurade.com/api/v2/checkout` with a `pack` from the OpenAPI
   document returns a `checkout_url` and its price to give the person; the
   credits arrive once they pay.

Revocation: `POST https://azurade.com/api/oauth/revoke` with `token=<the key>`
(RFC 7009), or the person deletes the key on their profile page. A revoked key
answers 401 from then on.

## Discovery

- `https://azurade.com/mcp/server-card`: MCP server card (SEP-2127).
- https://azurade.com/.well-known/oauth-protected-resource (RFC 9728) and
  https://azurade.com/.well-known/oauth-authorization-server (RFC 8414, with the
  `agent_auth` block for registration): OAuth metadata.

- `https://azurade.com/api/v2/openapi.json`: OpenAPI 3 document generated from the
  running code.
- `https://azurade.com/.well-known/api-catalog`: RFC 9727 linkset of the public API
  endpoints.
- `https://azurade.com/.well-known/ai-catalog.json`: ARD manifest listing every
  machine-readable document on this site.
- `https://azurade.com/.well-known/agent-skills/azurade-generation/SKILL.md`: how to run a
  generation end to end.
- `https://azurade.com/llms.txt`: the site itself.
