# auth.md — PAYATE

You are an agent. PAYATE's tools are **free and work without any authentication**.
Registering is optional: it gives you a bearer token that raises the MCP rate limit
from 60 to 600 requests per minute. This service supports **anonymous agentic
registration** only (no user accounts, no claim ceremony).

- Resource: `https://www.payate.com/` (MCP server: `https://www.payate.com/mcp/server.php`)
- Authorization server: `https://www.payate.com`
- Scope: `mcp.read` (read-only lookups)

## Step 1 — Discover

```http
GET https://www.payate.com/.well-known/oauth-protected-resource
GET https://www.payate.com/.well-known/oauth-authorization-server
```

The authorization-server metadata carries an `agent_auth` block with the
`identity_endpoint` and `identity_types_supported: ["anonymous"]`.

## Step 2 — Register (anonymous)

```http
POST https://www.payate.com/oauth/identity
Content-Type: application/json

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

Response:

```json
{
  "registration_id": "reg_...",
  "registration_type": "anonymous",
  "identity_assertion": "<service-signed JWT>",
  "assertion_expires": "2026-12-01T00:00:00Z",
  "pre_claim_scopes": ["mcp.read"],
  "post_claim_scopes": ["mcp.read"]
}
```

`identity_assertion` and `service_auth` registration types are not enabled and return
`identity_assertion_not_enabled` / `service_auth_not_enabled`. Registration is
rate-limited to 30 per hour per IP.

## Step 3 — Exchange the assertion for an access token (RFC 7523)

```http
POST https://www.payate.com/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&assertion=<identity_assertion>
```

Response: `{ "access_token": "...", "token_type": "Bearer", "expires_in": 3600, "scope": "mcp.read" }`

Tokens are RS256 JWTs; the public key is at `https://www.payate.com/oauth/jwks`.

## Step 4 — Use the token

```http
POST https://www.payate.com/mcp/server.php
Authorization: Bearer <access_token>
Content-Type: application/json

{"jsonrpc":"2.0","id":1,"method":"tools/list"}
```

Tools: `bin_lookup`, `luhn_check`, `iban_validate`, `swift_lookup`, `mcc_lookup`.

**Refresh:** when the access token expires, repeat Step 3 with the same
`identity_assertion` (valid 30 days). When that expires or `/oauth/token` returns
`invalid_grant`, repeat Step 2.

## Step 5 — Revoke (RFC 7009)

```http
POST https://www.payate.com/oauth/revoke
Content-Type: application/x-www-form-urlencoded

token=<access_token or identity_assertion>
```

## Notes

- Without a token you are limited to 60 MCP requests per minute per IP; a `429`
  response carries `WWW-Authenticate: Bearer resource_metadata="…"`.
- All data is public reference data (BIN ranges, SWIFT/BIC, MCC) or computed checks
  (Luhn, IBAN MOD-97). Nothing you send is stored.