# auth.md

You are an agent. This document describes how to authenticate to the Yutori API
so you can call it on your own behalf.

Yutori uses **API-key bearer authentication**. There is no interactive OAuth
authorization-code or token-exchange flow: you register once to obtain a
long-lived API key, then present it as a bearer token on every request. In the
[auth.md](https://github.com/workos/auth.md) / agent-auth vocabulary this is the
`anonymous` identity type with an `api_key` credential — the key identifies the
account, not an end user, and no per-request identity assertion is exchanged.

## Step 1 — Discover

Machine-readable discovery documents (served from `https://yutori.com`):

- Protected Resource Metadata (RFC 9728): `https://yutori.com/.well-known/oauth-protected-resource`
- Authorization Server Metadata (RFC 8414, with the `agent_auth` block): `https://yutori.com/.well-known/oauth-authorization-server`

The Protected Resource Metadata names the resource server (`https://api.yutori.com`), the
authorization server, and the accepted bearer method (`header`). The
Authorization Server Metadata carries the `agent_auth` block: it points
`register_uri` at the credential-issuance flow and lists
`identity_types_supported` (`anonymous`) plus the per-type credential shape
(`anonymous.credential_types_supported: ["api_key"]`).

## Step 2 — Register (obtain a credential)

Create an account and an API key at https://platform.yutori.com/sign-up. New accounts get
$5 in free credits. The key is the credential you will present; keep it secret.

## Step 3 — Use the API key

Send the key as a bearer token on every request to `https://api.yutori.com`:

```http
GET /v1/... HTTP/1.1
Host: api.yutori.com
Authorization: Bearer <YOUR_API_KEY>
```

The same bearer token authenticates the hosted MCP server (streamable HTTP) at
`https://api.yutori.com/mcp`.

## Step 4 — Handle auth failures

- `401 Unauthorized` — the key is missing, malformed, or revoked. Re-read this
  document and confirm the `Authorization: Bearer <key>` header is present and
  correct. If the key was revoked, mint a new one at https://platform.yutori.com.
- `403 Forbidden` — the key is valid but not entitled to the resource.
- `429 Too Many Requests` — back off and retry.

## Revocation

Rotate or revoke keys at https://platform.yutori.com. Revocation is immediate; a revoked key
returns `401` and you must register a new one (Step 2).

## Reference

- Authentication guide: https://docs.yutori.com/authentication
- API documentation: https://docs.yutori.com
- OpenAPI specification: https://docs.yutori.com/openapi.json
- Coding-agent quickstart: https://yutori.com/api/llms.txt