# auth.md

You are an agent. **Dropsaas** supports agentic registration: you can
provision your own scoped, revocable credential without a human first
creating an API key for you. This document describes exactly how.

## What you get

The credential is an opaque Bearer API key scoped to `read`. It lets you
call this service's authenticated agent endpoints (currently
`GET /api/agent/me`); the public storefront catalog under
`/api/storefront/{slug}` needs no credential at all. There is no `write`
access — this service does not expose agent-writable APIs.

## Discovery

- Protected Resource Metadata: `https://mail.dropsaas.net/.well-known/oauth-protected-resource`
- Authorization Server Metadata: `https://mail.dropsaas.net/.well-known/oauth-authorization-server`

The `agent_auth` block in the Authorization Server metadata lists the
`register_uri`, supported `identity_types`, credential type, `claim_uri`,
and `revocation_uri`. Only the **anonymous** method is supported.

## Step 1 — Register (anonymous)

```http
POST https://mail.dropsaas.net/api/agent/register
Content-Type: application/json

{ "type": "anonymous" }
```

Response (201):

```json
{
  "registration_id": "reg_...",
  "registration_type": "anonymous",
  "access_token": "agtk_...",
  "token_type": "Bearer",
  "scopes": ["read"],
  "expires_at": "2027-07-03T00:00:00+00:00",
  "claim_token": "agtc_...",
  "claim_uri": "https://mail.dropsaas.net/api/agent/claim",
  "resource": "https://mail.dropsaas.net/api/agent/me"
}
```

Keep `access_token` — it is shown once. Hold `claim_token` in memory only
if you intend to run the optional claim ceremony (Step 3).

## Step 2 — Use the credential

```http
GET https://mail.dropsaas.net/api/agent/me
Authorization: Bearer <access_token>
```

A `401` with `WWW-Authenticate: Bearer error="invalid_token"` means the
credential was revoked or expired — register again.

## Step 3 — Claim (optional)

To bind the credential to a real user account (for attribution and so the
user can revoke it), start a claim ceremony:

```http
POST https://mail.dropsaas.net/api/agent/claim
Content-Type: application/json

{ "claim_token": "agtc_...", "email": "user@example.com" }
```

The response returns a `claim.user_code` and `claim.verification_uri`.
Show both to the user: they open the link, sign in to Dropsaas, and type
the 6-digit code to confirm. Poll `GET /api/agent/me` — `claimed` flips to
`true` once they finish. The code goes into the page they land on, never
back to you.

## Revocation

```http
POST https://mail.dropsaas.net/api/agent/revoke
Content-Type: application/json

{ "token": "agtk_..." }
```

Idempotent, always `200`. A user can also revoke from their account. After
revocation, restart at Step 1.