# Auth for agents

Ukoshiku exposes personal data (recipes, meal plan, store cart) to agents only through the MCP endpoint at `POST https://ukoshiku.com/api/mcp`, protected by OAuth 2.1. There is no separate API key — every agent authenticates as itself, then a human grants it access to their own account.

## Discover

1. Fetch protected-resource metadata (RFC 9728): `GET https://ukoshiku.com/.well-known/oauth-protected-resource/api/mcp`.
   It lists `authorization_servers` and the supported `scopes_supported`.
2. Fetch authorization-server metadata (RFC 8414) from that server: `GET https://ukoshiku.com/.well-known/oauth-authorization-server`.
   It gives you `registration_endpoint`, `authorization_endpoint`, and `token_endpoint`.

## Pick a method

Only one method is supported: OAuth 2.1 authorization code with PKCE (`code_challenge_method=S256`). There is no client secret and no service-account flow — every session is tied to the human who approves it.

## Register

`POST https://ukoshiku.com/api/mcp/oauth/register` with a JSON body `{ "client_name": "...", "redirect_uris": ["..."] }` registers a new OAuth client and returns a `client_id`. Registration is open (no admin approval needed) — this is dynamic client registration, not identity verification.

## Claim

Send the human to `GET https://ukoshiku.com/api/mcp/oauth/authorize` with your `client_id`, `redirect_uri`, a PKCE `code_challenge`, and the `scope` you need (space-separated, see `scopes_supported` above: `ukoshiku.read`, `ukoshiku.drafts`, `ukoshiku.plan`, `ukoshiku.shopping-list`). The human logs into their own Ukoshiku account and approves the request there; they can review and revoke it later at `https://ukoshiku.com/mcp/connections`.

## Exchange

On approval you receive an authorization `code` at your `redirect_uri`. Exchange it at `POST https://ukoshiku.com/api/mcp/oauth/token` (grant_type=authorization_code, with your PKCE `code_verifier`) for an access token (15 minutes) and a refresh token (30 days). Use `grant_type=refresh_token` on the same endpoint to renew.

## Use the access_token

Call `POST https://ukoshiku.com/api/mcp` with `Authorization: Bearer <access_token>` and a JSON-RPC 2.0 body. Start with `{"method":"initialize"}` (no auth required for this one call), then `tools/list` to see the exact argument schemas, then `tools/call`. Actions that change data (`ukoshiku_propose_*`) never write anything by themselves — they return a confirmation link the human opens inside Ukoshiku, unless the human has explicitly turned on auto-approval for that client.

## Errors

A request without a valid bearer token gets `401` with a spec-shaped header: `WWW-Authenticate: Bearer resource_metadata="https://ukoshiku.com/.well-known/oauth-protected-resource/api/mcp"`. Tool errors come back as a normal JSON-RPC result with `isError: true` and a human-readable message, not as an HTTP error — check that field.

## Revocation

The human revokes a client's access at `https://ukoshiku.com/mcp/connections` at any time; the access token then stops working immediately on the next call. There is no separate agent-initiated revocation endpoint yet — letting the short-lived (15 minute) access token expire is the closest equivalent.