# Peaje authentication

This API uses no API keys and no OAuth. Access is bought per request with MPP
(Machine Payments Protocol, HTTP 402). The credential IS the payment.

Structured as the auth.md spec prescribes (https://github.com/workos/auth.md),
with one deviation stated up front: the only `identity_types_supported` value
here is `anonymous`. There is nothing to register and no account to hold, so
the Register and Revocation steps collapse into "not applicable". That is not
an omission, it is the design: an agent that can pay is already authorized.

## Step 1 — Discover

Start at `https://usepeaje.com/.well-known/oauth-protected-resource` (RFC 9728). It names this
resource, its `agent_auth` block, and links back to this document. You can also
reach it the short way: call any priced endpoint with no credentials and read the
`WWW-Authenticate` header it returns.

```bash
curl -i https://usepeaje.com/<route>
```

## Step 2 — Pick a method

The 402 carries one `WWW-Authenticate: Payment` challenge per supported network.
Pick the one your wallet can settle. See "Payment networks" below.

## Step 3 — Register

Not applicable. `identity_types_supported` is `["anonymous"]`: there is no
registration endpoint, no client_id and no account. Skip to step 4.

## Step 4 — Claim ceremony

Not applicable for the same reason. There is no `identity_assertion` flow and no
`service_auth` flow here, so no ID-JAG (`urn:ietf:params:oauth:token-type:id-jag`)
is minted or exchanged. Where those flows would prove *who* you are, this API only
needs proof that you *paid*.

## Step 5 — Exchange the assertion

The payment replaces the assertion exchange. Settle the challenge on the network
you picked and build the credential from the signed authorization:

```bash
npx mppx@latest https://usepeaje.com/<route>
```

## Step 6 — Use the access_token

Retry the request with the credential in the `Authorization` header. The response
carries a `Payment-Receipt` header as proof of what you bought.

```bash
curl -i -H "Authorization: Payment <credential>" https://usepeaje.com/<route>
```

Credentials are single-use and scoped to one request. There is no bearer token to
store, so there is nothing to leak.

## Errors

- `402` with no credential: not an error, it is the price. Always includes a fresh challenge.
- `402` after paying: the credential was invalid or expired. Retry by paying the new challenge.
- `404`: unknown route. JSON body with `error` and `hint`.
- `502`: you paid and the origin failed. The payment is refunded on-chain automatically and the response carries `Payment-Refund`.

## Revocation

Not applicable. Nothing is issued that could be revoked: each credential dies with
the request that used it. To stop spending, stop paying challenges.

## Payment networks

- **Arbitrum** (testnet): USDC · chainId 421614 · token `0x75faf114eafb1BDbe2F0316DF893fd58CE46AA4d`
- **Arbitrum · USDG** (testnet): USDG · chainId 421614 · token `0xFFC95faa3d63Cde504a05B567C600B78C0b41892`
- **Robinhood** (testnet): USDG · chainId 46630 · token `0x7E955252E15c84f5768B83c41a71F9eba181802F`
- **Tempo** (testnet): pathUSD · chainId 42431 · token `0x20c0000000000000000000000000000000000000`
- **Arc** (testnet): USDC · chainId 5042002 · token `0x3600000000000000000000000000000000000000`

Protocol spec: https://mpp.dev · Discovery: https://usepeaje.com/openapi.json · x402 Bazaar: https://usepeaje.com/discovery/resources