# Ration auth.md

Ration supports agent-first onboarding for MCP and REST API access. Human signup via Better Auth (Google + magic link) remains the primary path for browser users.

## Registration metadata

- Skill: `https://ration.mayutic.com/auth.md`
- Register: `https://ration.mayutic.com/api/agent/auth` (POST; credential type: `api_key`)
- Claim: `https://ration.mayutic.com/api/agent/auth/claim`
- Reissue claim link: `https://ration.mayutic.com/api/agent/auth/claim/reissue` (POST; Bearer agent API key)

## Issuer

`https://ration.mayutic.com/api/auth`

## Flows

### Tier 0 — Anonymous self-registration

Agents can provision a kitchen without human signup:

```http
POST https://ration.mayutic.com/api/agent/auth
Content-Type: application/json

{ "type": "anonymous", "client_hint": "cursor" }
```

Returns (once): `api_key`, `claim_token`, `claim_url`, `organization_id`, `mcp_endpoint`, and `scopes` (mcp:read, mcp:inventory:write, mcp:galley:write, mcp:manifest:write, mcp:supply:write, mcp:preferences:write).

Tier 0 keys have **full MCP write scopes** immediately. Claiming transfers ownership to a verified human — it does **not** widen scopes or unlock tier capacity.

### Tier 1 — User-claimed / verified email

Humans claim an agent kitchen via OTP email and Terms of Service acceptance:

1. `POST https://ration.mayutic.com/api/agent/auth/claim` — send OTP to email
2. `POST https://ration.mayutic.com/api/agent/auth/claim/complete` — verify OTP, accept ToS (`tos_accepted: true`, `tos_version`), complete claim

Claim page: https://ration.mayutic.com/connect/claim

Scopes after claim: mcp:read, mcp:inventory:write, mcp:galley:write, mcp:manifest:write, mcp:supply:write, mcp:preferences:write (unchanged from Tier 0).

### Claim recovery

Users must always be able to claim an active unclaimed kitchen:

- **Option B (passive):** Each API/MCP authentication slides `claimTokenExpiresAt` forward by 180 days while `pending_claim`.
- **Option A (active):** `POST https://ration.mayutic.com/api/agent/auth/claim/reissue` with `Authorization: Bearer <agent-api-key>` returns a new `claim_token` and `claim_url` (invalidates the prior token).

If both the API key and claim URL are lost, recovery requires support contact.

## Time limits & retention

| Policy | Duration | Applies to |
|--------|----------|------------|
| Initial claim token validity | 180 days from registration | `pending_claim` only |
| Claim token slide (Option B) | Resets to 180 days from last auth | `pending_claim` only |
| Claim reissue (Option A) | Bearer agent API key; 3/hour per key | `pending_claim` only |
| Claim OTP validity | 10 minutes | Per OTP send |
| Claim OTP max attempts | 5 per OTP | Per registration |
| Orphan kitchen deletion | 180 days idle (last auth or `createdAt`) | `pending_claim` only |
| Pre-claim MCP write rate limit | 10/min org + per key | `preClaim: true` |
| Agent registration rate limit | 5/min per IP | Registration |

Claimed kitchens are never purged by the orphan job.

## OAuth (recommended for interactive MCP clients)

Paste `https://mcp.ration.mayutic.com/mcp` into a compatible client and complete browser OAuth sign-in.

- Authorization server metadata: `https://ration.mayutic.com/.well-known/oauth-authorization-server`
- MCP protected resource: `https://mcp.ration.mayutic.com/mcp` (see MCP host PRM)
- REST protected resource: `https://ration.mayutic.com/.well-known/oauth-protected-resource`

## Discovery

- API catalog: `https://ration.mayutic.com/.well-known/api-catalog`
- MCP server card: `https://ration.mayutic.com/.well-known/mcp/server-card.json`
- Agent skills: `https://ration.mayutic.com/.well-known/agent-skills/index.json`
- API docs: `https://ration.mayutic.com/docs/api`