# Kestrel Notes auth.md

You are an agent that wants to call the Kestrel Notes API on a user's behalf. This file tells you how to
register and obtain a credential without a human in the loop.

- **Resource server:** `https://kestrel-e.docka.ai/api/v1`
- **Authorization server:** `https://kestrel-e.docka.ai`

## 1. Discover

- Protected resource metadata: `GET https://kestrel-e.docka.ai/.well-known/oauth-protected-resource`
- Authorization server metadata: `GET https://kestrel-e.docka.ai/.well-known/oauth-authorization-server` — the
  `agent_auth` block lists `register_uri`, `identity_types_supported` (`anonymous`) and
  `credential_types_supported` (`api_key`).

## 2. Register (anonymous)

```http
POST /agent/auth HTTP/1.1
Host: kestrel-e.docka.ai
Content-Type: application/json

{"name": "<who you are and who you act for>"}
```

Returns `agent_id`, `api_key` (prefix `kn_agent_`) and a one-time `claim_code`. Show the claim code to
your human operator; they can bind this identity to their dashboard later. The identity starts on the
Free plan with the same limits as a human account.

## 3. Use the credential

```http
GET /api/v1/me HTTP/1.1
Host: kestrel-e.docka.ai
Authorization: Bearer kn_agent_...
```

## 4. Claim (optional, human)

`POST /agent/auth/claim` with `{"claim_code": "...", "email": "..."}` binds the identity to a human account.

## 5. Revoke

`POST /agent/auth/revoke` with the credential in `Authorization` revokes it immediately.

## 6. Errors

| Status | Meaning | What to do |
|---|---|---|
| 400 | malformed body | fix the JSON |
| 401 | missing/invalid credential | register again |
| 429 | too many registrations from your address | wait 60 s |