# auth.md — agent access to CanIEnter

This file is the authentication skill manifest for AI agents using the
CanIEnter visa & entry requirements API (https://api.canienter.com). Machine-readable metadata:
[/.well-known/oauth-authorization-server](https://api.canienter.com/.well-known/oauth-authorization-server) and
[/.well-known/oauth-protected-resource](https://api.canienter.com/.well-known/oauth-protected-resource).

**The short version: you do not need an account.** Anonymous free-tier access
works immediately, and the paid tier is authenticated by payment itself (x402,
USDC on Base) — no API key, no OAuth token, no registration.

## Access tiers

| Tier | Auth | Quota |
|------|------|-------|
| Anonymous free | none | 5 checks/day/IP (`GET /free/check`) |
| Registered agent | Bearer token (this page) | 20 checks/day/client (`GET /free/check`) |
| Paid | x402 payment per request | unlimited (`GET /v1/check` $0.03, `GET /v1/passport/{iso3}` $0.15, `POST /v1/trips/evaluate` $0.10) |

## Register (anonymous, RFC 7591)

Registration is open and anonymous — no email, no identity assertion:

```
POST https://api.canienter.com/oauth/register
Content-Type: application/json

{"client_name": "my-travel-agent"}
```

Response includes `client_id` and `client_secret` (shown once — store it).
Limited to 3 registrations/day/IP.

## Exchange (client_credentials)

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

grant_type=client_credentials&client_id=...&client_secret=...
```

Returns `{"access_token": "...", "token_type": "Bearer", "expires_in": 3600}`.
Tokens are opaque (not JWTs) and expire after 1 hour; request a new one at
any time. `client_secret_basic` is also accepted.

## Use

```
GET https://api.canienter.com/free/check?passport=NLD&destination=JPN
Authorization: Bearer <access_token>
```

An invalid or expired token gets `401` with a `WWW-Authenticate` header
pointing back to the protected-resource metadata.

## Claiming

There is nothing to claim: registered clients are quota identities only, with
no account, stored personal data, or dashboard. Registrations expire after 90
days, and losing a `client_secret` just means registering again.

## Skip all of this with x402

Agents that can pay per request should prefer `/v1/check`: call it, receive
`402 Payment Required` with x402 payment instructions, pay $0.03 in USDC on
Base, retry with the payment header. No registration, no token, no rate limit.
See [/llms.txt](https://api.canienter.com/llms.txt) for the full protocol walkthrough.