# auth.md

You are an agent. This document tells you how agent registration and credential
provisioning work for **pirouter** (pirouter.ai), and what you can access today
without a credential.

pirouter is live. No OAuth/OIDC discovery metadata is published and there is no
agent-verified (ID-JAG) or email-verified registration — this document is the source
of truth for agent registration. Identity types supported: anonymous (read-only) and
user-claimed API key (created by the user in the Console). Follow the steps in order.

## Step 1 — Use the anonymous read-only surface (no registration)

The catalog surface requires no registration and no credential. You can call it right
now, anonymously:

```http
GET /api/models HTTP/1.1
Host: pirouter.ai
```

```http
POST /mcp HTTP/1.1
Host: pirouter.ai
Content-Type: application/json

{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}
```

## Step 2 — Register (user-mediated)

Registration for the paid routing API is user-claimed — a human completes the claim
ceremony in a browser; agents cannot self-register:

1. Send your user to the Console sign-in at https://app.pirouter.ai/sign-in — they sign in with an
   email one-time code or with GitHub; no invite is needed.

## Step 3 — Claim ceremony (user completes)

The user claims the account in the Console, creates an API key, and tops up a prepaid
wallet (pay as you go, no deposit fee). That user-provisioned API key is the credential
you will use — treat it as a secret; do not log it.

## Step 4 — Use the credential

- Authenticated API requests use `Authorization: Bearer <api-key>` headers
  (bearer method: header).
- Credential types supported: user-provisioned API key (bearer token). The anonymous
  read-only surface in Step 1 needs no credential at all.
- One key works across the whole model catalog; OpenAI, Anthropic and Gemini
  protocols are terminated natively.
- Revocation: the user can revoke or rotate the API key in the Console at any time;
  a revoked key returns 401 and you must ask the user to issue a new one.

## What you can access without a credential

- Model catalog API: https://pirouter.ai/api/models (public, read-only, no auth)
- MCP server (read-only catalog tools): https://pirouter.ai/mcp
- OpenAPI description: https://pirouter.ai/openapi.json
- API catalog (RFC 9727): https://pirouter.ai/.well-known/api-catalog
- Site index for LLMs: https://pirouter.ai/llms.txt