# auth.md — Arete Diamond Agent Authentication

Catalogue **reads** (diamond & jewellery search, lookup, encyclopedia, shipping
& returns) are **open** — no credential required. Higher rate limits use an API
key. The **write path** (checkout) is buyer-consent via a scoped payment token,
never an agent scope.

## How to register

Register **programmatically — no human needed**. POST to the registration
endpoint and receive an `ak_`-prefixed **read** key instantly:

```sh
curl -X POST https://aretediamond.cz/oauth/register \
  -H 'content-type: application/json' \
  -d '{"client_name":"My Shopping Agent"}'
```

The `201` response returns your credential **once** (only a hash is stored):

- `client_secret` — your `ak_…` API key. Send it as `Authorization: Bearer ak_…`,
  or exchange it for a short-lived token at `https://aretediamond.cz/oauth/token`.
- `client_id` — your agent id.
- `client_secret_expires_at` — the key's expiry (90 days; re-register to refresh).
- `registration_access_token` + `registration_client_uri` — self-manage: revoke
  any time with `DELETE https://aretediamond.cz/oauth/register/{client_id}` and
  `Authorization: Bearer <registration_access_token>` (RFC 7592).

The self-service key is **read scope only** — it raises your rate limit and grants
the open catalogue. It can **never** authorize a purchase: checkout is
buyer-consent (a scoped, single-use payment token the shopper approves), not an
agent scope. For an elevated (`trusted`/`access`) key, contact an Arete operator
at `mailto:agents@aretediamond.cz`.

Scopes:

- `read` — open catalogue reads + higher rate limit (120 req/min vs 60 anonymous); self-service, instant
- `trusted` — reads + higher rate limit (240 req/min) + escalation trust (operator-issued)
- `access` — an operator-issued key (for the require-key gate)

When the require-key gate is on, **any** valid key — including a self-service
`read` key — satisfies it; the gate controls anonymous throughput, not
confidentiality (reads are open and identical for every caller).

## How to authenticate

Two equivalent options:

1. **Direct** — send the key as a Bearer token: `Authorization: Bearer ak_...`
2. **OAuth 2.0 client-credentials** — exchange the key for a short-lived token at
   `https://aretediamond.cz/oauth/token` and send that. Discovery:
   `https://aretediamond.cz/.well-known/oauth-authorization-server`. The protected write
   resource is described at `https://aretediamond.cz/.well-known/oauth-protected-resource`.

Tokens are opaque to reads (reads never require them). A `read` key can only ever
mint a `read`-scoped token; it can never obtain `checkout`.

## agent_auth

The `agent_auth` fields below are also published under `agent_auth` in the AS
metadata at `https://aretediamond.cz/.well-known/oauth-authorization-server` (that copy omits
the `authorization_server` / `protected_resource` self-references shown here).

```json
{
  "skill": "https://aretediamond.cz/auth.md",
  "register_uri": "https://aretediamond.cz/oauth/register",
  "identity_types_supported": [
    "anonymous",
    "service_auth"
  ],
  "credential_types_supported": [
    "api_key",
    "oauth2_access_token"
  ],
  "service_auth": {
    "register_uri": "https://aretediamond.cz/oauth/register",
    "credential_types_supported": [
      "api_key",
      "oauth2_access_token"
    ],
    "revocation_uri": "https://aretediamond.cz/oauth/register/{client_id}"
  },
  "registration_endpoint": "https://aretediamond.cz/oauth/register",
  "anonymous": {
    "register_uri": "https://aretediamond.cz/oauth/register",
    "credential_types_supported": [
      "api_key"
    ],
    "revocation_uri": "https://aretediamond.cz/oauth/register/{client_id}",
    "scopes_supported": [
      "read"
    ]
  },
  "token_endpoint": "https://aretediamond.cz/oauth/token",
  "grant_types_supported": [
    "client_credentials"
  ],
  "scopes_supported": [
    "read",
    "checkout"
  ],
  "authorization_server": "https://aretediamond.cz/.well-known/oauth-authorization-server",
  "protected_resource": "https://aretediamond.cz/.well-known/oauth-protected-resource"
}
```

Self-issued keys are self-revocable: `DELETE https://aretediamond.cz/oauth/register/{client_id}`
with your `registration_access_token` invalidates the key immediately. Operator-
issued keys are revoked by contacting `mailto:agents@aretediamond.cz`.

Reads never require a credential; do not treat the open catalogue as gated.