# auth.md — BlinkCodes (blinkcodes.com)

How an autonomous agent authenticates against blinkcodes.com. Short version: **it
doesn't have to.** The whole buying flow — browse, order, pay, collect the code
— is anonymous. There is no registration step to complete before you can trade.

## 1. Public API — no credentials

Every endpoint under `https://blinkcodes.com/api/public/` is open, CORS-enabled and
unauthenticated:

- `GET  /api/public/products`, `/api/public/products/{id}` — catalog
- `GET  /api/public/esim/countries`, `/api/public/esim/bundles` — eSIM coverage
- `GET  /api/public/phone/info` — rentable phone numbers
- `POST /api/public/create-order` — create an order (needs an `Idempotency-Key` header)
- `POST /api/public/create-heleket-payment` — hosted crypto checkout link
- `GET  /api/public/order/{id}?token=…` — order status + delivered goods

Machine-readable description: `https://blinkcodes.com/openapi.json`.
Agent guide: `https://blinkcodes.com/llms.txt`.
MCP server: `https://blinkcodes.com/mcp` (Streamable HTTP, card at
`https://blinkcodes.com/.well-known/mcp/server-card.json`).

## 2. Per-order capability token (the only credential we issue)

`POST /api/public/create-order` returns:

```json
{ "order_id": "…", "access_token": "…", "price_rub": 1234.0, "status": "pending" }
```

`access_token` is a bearer capability scoped to that single order. Pass it as
`?token=<access_token>` on `GET /api/public/order/{id}` to read status, the
gift-card code, the eSIM QR payload or the rented number. It grants nothing
else. Store it: without it the order can only be recovered by contacting
support from the delivery email address.

- Provisioning endpoint: `POST https://blinkcodes.com/api/public/create-order`
- Credential type: opaque bearer token, per order, no expiry, no refresh
- Revocation: none — the token dies with the order record; ask support to
  invalidate an order at support@blinkcodes.com
- Identity: the delivery email you submit. No verification step, no password.

## 3. Payment is the real gate

Nothing is delivered before money arrives. `create-heleket-payment` returns a
hosted crypto checkout URL, which a wallet can settle without a browser session.
Card rails exist for humans on the website; crypto is the rail meant for agents.
When the payment is confirmed, fulfillment runs and the order flips to
`completed`. An agent that can pay the invoice needs no other credential.

Autonomous machine-payment rails (x402 / agentic checkout) are **not live yet**.

## 4. What we deliberately do not publish

- **No OAuth 2.0 / OIDC authorization server.** There are no user accounts on
  blinkcodes.com, so `/.well-known/openid-configuration`,
  `/.well-known/oauth-authorization-server` and
  `/.well-known/oauth-protected-resource` are intentionally absent. Publishing
  them would advertise an issuer, a token endpoint and a JWKS URI that all 404.
  If you are looking for how to authenticate: you don't need to (§1), or you
  hold a per-order token (§2).
- **No API keys.** Nothing on the public surface is rate-limited per-identity,
  so there is nothing for a key to unlock. Ask at support@blinkcodes.com if you need
  a higher-volume reseller integration — that is a contract, not a signup form.

## 5. Staff endpoints (not for agents)

Administrative routes require a staff login, are not part of the public
contract, are not documented here, and will 401.

Contact: support@blinkcodes.com