# Agent Pass

> Identity, accounts and billing for AI agents and their users. One base layer: globally unique
> agent identity, verifiable credentials, and unified accounts and billing — humans and agents
> share a single subject model.

Agent Pass is the account and billing base layer that other TuringCorp products plug into.
Those products never build their own accounts and never touch money: they report usage and ask
Agent Pass to allow or deny each call.

## What you can do with the API

1. **Create an account** — email sign-up with a 6-digit verification code.
2. **Get an API key** — returned once on sign-up and on each sign-in.
3. **Read your account** — profile, status and balance.
4. **Reset a password** — code by email; all previous credentials are revoked.
5. **Contact support** — file a ticket from code, no mailbox needed.

## Authentication

Every account endpoint takes:

    Authorization: Bearer <apiKey>

Embeddable: include https://agent-pass.turingcorp.net/embed.js and call AgentPass.open() for a popup that signs in, shows the balance, tops up and copies the Agent Pass. Guide: /embed.md

## Rate limits

- Verification codes: one send per address per 60 seconds, max 5 per 24 hours per address.
- Codes expire after 10 minutes and are single use; 5 wrong attempts void the code.
- Support tickets: 5 per email per day, 50 per network per day.
- Sign-in: throttled per address and per network.

## Errors

All errors are JSON with a stable, machine-readable code:

    {"ok": false, "error": {"code": "insufficient_balance", "message": "...", "retryAfterSeconds"?: 30}}

Never branch on `message`; branch on `code`.

Authorization reasons are distinguishable on purpose, because the fixes differ:
invalid_credential (register or get a new key), insufficient_balance (top up),
account_suspended (contact support), rate_limited (retry later), amount_above_ceiling.
The message field is written to be shown to the end user, so an agent can act on it.

Failure policy: a NEW hold is fail-closed when Agent Pass is unreachable; holds already
issued stay valid, so a caller can finish in-flight work and report it afterwards.

## Notes for agents

- Account existence is never disclosed: sign-up and password-reset return identical responses
  whether or not the address is registered.
- Money is stored as integer minor units. Balances are derived from an append-only ledger.
- Credentials: your Agent Pass expires after 7 days and is revocable; an expired or revoked one returns `invalid_credential` (HTTP 401). Sign in again to renew it (POST /api/v1/auth/login issues a fresh Agent Pass; POST /api/v1/me/agent-pass/rotate replaces a still-valid one). The account page keeps a separate browser session, so the Pass expiring does not sign you out there.
- English only.

## Endpoints

    POST /api/v1/auth/register/start          { email }
    POST /api/v1/auth/register/complete       { email, code, password }   -> { account, apiKey, expiresAt }
    POST /api/v1/auth/login                   { email, password }         -> { account, apiKey, expiresAt }
    POST /api/v1/auth/password/reset/start    { email }
    POST /api/v1/auth/password/reset/complete { email, code, password }
    POST /api/v1/auth/logout
    GET  /api/v1/me                                                       -> { account, balance }
    GET  /api/v1/me/credentials                                           -> { maxActive, credentials[] }
    POST /api/v1/me/credentials/revoke        { credentialId }
    POST /api/v1/me/agent-pass/rotate                        Re-roll the Agent Pass (revokes every Agent Pass; browser sessions are kept)
    GET  /api/v1/ledger                                                   -> { available, entries[] }
    GET  /api/v1/topup/options                                            -> { configured, amounts[] }
    POST /api/v1/topup                        { amount }
    POST /api/v1/support                      { email, subject?, message } -> { ticketId }
    GET  /health

## For consumers (products)

A product authenticates with its own PRODUCT credential (Authorization: Bearer <product key>),
never a user key, and names the end user in the body. Mode B: the base layer keeps no price list,
so "amount" is the caller's own figure and is held exactly as sent. Product credentials are issued by the operator, not self-service: an unknown key returns 401 invalid_product_credential. Registered products: workflow, workflow-test, poe-channel (metered), cloudpal. A new product must be registered by the operator, on the account owner's instruction, before it can call.

    POST /api/v1/authorize         { agentPass, sku?, amount, idempotencyKey } -> { allowed, accountId, holdId, expiresAt }
                                   amount 0 = authenticate only: accountId with no hold and no SKU
    POST /api/v1/usage             { holdId, amount, productStatus?, idempotencyKey } -> { charged, released }
    GET  /api/v1/products/usage?from=&to=                -> { totals, events[] }
    GET  /api/v1/products/holds                          -> { openHolds[] }
    GET  /api/v1/products/skus                           -> { skus[] }
    POST /api/v1/products/skus     { sku, maxAmount?, holdTtlSeconds? }
    POST /api/v1/products/rotate

## Machine-readable entry points

    https://agent-pass.turingcorp.net/llms.txt        this index
    https://agent-pass.turingcorp.net/llms-full.txt   everything in one file
    https://agent-pass.turingcorp.net/index.md        agent brief (Markdown)
    https://agent-pass.turingcorp.net/openapi.json    OpenAPI 3.1 specification
    https://agent-pass.turingcorp.net/api             API reference (plain text)
    https://agent-pass.turingcorp.net/sitemap.xml     sitemap
    https://agent-pass.turingcorp.net/embed.md        embedding guide (popup launcher)

## Contact

File a ticket: POST /api/v1/support, or use the form at https://agent-pass.turingcorp.net/support