# Authentication — eSIM Global API

## TL;DR for agents

**You do not need to authenticate.** Every endpoint under `https://esim-global-compare.netlify.app/api/v1` answers
anonymous requests. Call it and go.

```
GET https://esim-global-compare.netlify.app/api/v1/compare?country=Japan&days=10
```

A token is optional and buys exactly one thing: a higher rate limit.

## Rate limits

| Tier | Limit | How |
|---|---|---|
| Anonymous | 60 requests / minute per IP | no credentials |
| Registered | 600 requests / minute per client | bearer token |

Exceeding a limit returns `429` with a `Retry-After` header. Back off rather than
retrying immediately.

## Registering as an agent

1. Discover the authorization server:

   ```
   GET https://esim-global-compare.netlify.app/.well-known/oauth-protected-resource
   GET https://mtoxtyjzxvzuizxoapdm.supabase.co/auth/v1/.well-known/openid-configuration
   ```

2. Obtain a token from the issuer using the `authorization_code` grant.

3. Send it as `Authorization: Bearer <token>` to any endpoint under `https://esim-global-compare.netlify.app/api/v1`.

### Identity types accepted

- `oauth2` bearer tokens from the issuer above.
- `web-bot-auth` — HTTP Message Signatures (RFC 9421). If your crawler publishes a
  key directory at `/.well-known/http-message-signatures-directory`, sign your
  requests and we will attribute them to you without a token. Ours is published at
  `https://esim-global-compare.netlify.app/.well-known/http-message-signatures-directory`.

### Scopes

| Scope | Grants |
|---|---|
| `esim:read` | Everything the anonymous tier can do, at the registered rate limit |
| `esim:bulk` | Full dataset exports without pagination |

## Revocation

Tokens are revoked at the issuer's standard revocation endpoint, listed in its
OpenID configuration document.

## Terms

Data is published under CC BY 4.0. Attribute as "eSIM Global" and link back to
https://esim-global-compare.netlify.app. Prices are observations with a `captured_at` date — carry that date
through to whoever reads your output.

## Machine-readable pointers

- OpenAPI: `https://esim-global-compare.netlify.app/openapi.json`
- MCP server card: `https://esim-global-compare.netlify.app/.well-known/mcp/server-card.json`
- Protected resource metadata: `https://esim-global-compare.netlify.app/.well-known/oauth-protected-resource`
- API catalog: `https://esim-global-compare.netlify.app/.well-known/api-catalog`
- Agent skills: `https://esim-global-compare.netlify.app/.well-known/agent-skills/index.json`