# ProxyLLM auth.md

You are an agent. ProxyLLM is an OpenAI-compatible LLM gateway; it turns a human's flat-fee ChatGPT/Codex subscription into API-shaped capacity with fallback lanes, logs, and budgets. This file tells you how to authenticate, and how to create an account on your operator's behalf without a browser or captcha. Docs index: https://proxyllm.ai/llms.txt - OpenAPI: https://proxyllm.ai/openapi.json - Agent card: https://proxyllm.ai/.well-known/agent-card.json

The flow in one line: sign up with your operator's email, verify the emailed code, store the account token you receive, hand your operator the checkout link, poll until the membership is active, then provision and serve.

## Tokens

Every request authenticates with the Authorization header; the Bearer prefix is optional.

- Routing key (pllm_...): inference. Put it in OPENAI_API_KEY and call /v1/chat/completions or /v1/responses at https://api.proxyllm.ai.
- Account token (sk_ read+write, rk_ read-only): management under /v1/organizations/... . Signup below returns an sk_ token.

GET https://api.proxyllm.ai/v1/models needs no token.

## Step 1 - Sign up (email OTP)

POST https://proxyllm.ai/api/auth?action=agent-signup
Content-Type: application/json

{"email": "your-operator@example.com", "source": "authmd"}

source is optional: a short slug naming what sent you here (mcp, authmd, clawhub, bazaar, content). Pass it so your path gets credit.

Response: {"ok": true, "new_account": true, "account_expires_at": "<ISO date>"}

A 6-digit code is emailed to that inbox. The email states that an AI agent initiated the signup. Rules: disposable email domains are refused; at most 3 codes per email per hour; the account is removed automatically at account_expires_at (48 hours after signup) unless a membership is activated. If the email already has a ProxyLLM account, the code signs in to it instead and no deadline is added.

## Step 2 - Verify, receive the account token

POST https://proxyllm.ai/api/auth?action=agent-verify
Content-Type: application/json

{"email": "your-operator@example.com", "code": "123456"}

Response:

{
  "account_token": "sk_...",
  "token_scope": "read_write",
  "plan": "free",
  "payment": {
    "checkout_url": "https://whop.com/checkout/...",
    "price_usd": 129,
    "account_expires_at": "<ISO date>",
    "poll": "GET /v1/organizations/me until plan is \"pro\"",
    "message": "<a sentence you can relay to your operator verbatim>"
  }
}

account_token is returned exactly once; store it securely. Your operator also receives one email naming the deadline and the checkout link.

## Step 3 - Get the membership activated (human step)

Until a membership is active, every management endpoint answers 402 with the same payment block. Relay payment.message and payment.checkout_url to your operator; a human completes the checkout. Then poll:

GET https://api.proxyllm.ai/v1/organizations/me
Authorization: Bearer sk_...

While unpaid the response carries plan "free" plus the payment block. When plan is "pro", proceed.

If the deadline passes first, every call answers 410 account_expired: the account was removed to prevent spam. You may sign up again with the same email.

## Step 4 - Provision and serve

- Create a routing key: POST https://api.proxyllm.ai/v1/organizations/routing-keys with {"label": "..."} -> raw_key (pllm_..., returned once). Docs: https://proxyllm.ai/docs/api/routing-keys.md
- Wire its lanes over the same API: GET .../routing-keys?include=lanes lists your wireable lanes (codex sessions, bridges, saved provider keys) with ids; then POST with a providers array, or PATCH .../routing-keys?id=<id> with {"mode": "fallback", "providers": [{"provider": "codex", "codex_session_id": "..."}]} to rewire. Shapes: https://proxyllm.ai/openapi.json
- Add capacity: connect a Codex subscription by running `proxyllm codex connect` on a machine where `codex login` has already been completed (docs: https://proxyllm.ai/docs/api/codex-session.md), or register a self-hosted Claude Code bridge via POST .../bridges. Saving metered provider API keys is a dashboard step today.
- Inference: POST https://api.proxyllm.ai/v1/chat/completions with the pllm_ key. Introspect what a key can do: GET https://api.proxyllm.ai/v1/key. Docs: https://proxyllm.ai/docs/api/key.md

## Error vocabulary

- 400: bad email, disposable domain, or wrong/expired code. Fix the input.
- 402 payment_required: no active membership. Relay the payment block; poll me.
- 410 account_expired: the 48h window closed. Sign up again.
- 429: rate limited. Back off and retry later.
- 502: the code email failed to send. Retry.

Full API reference: https://proxyllm.ai/docs/api.md