> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ascii.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent sign-in

> How an agent registers itself with Box, claims a human, and starts the 7-day free trial.

Agents can onboard to Box without a human pasting an API key. Box implements [auth.md](https://workos.com/blog/agent-registration-with-auth-md), the WorkOS agentic registration protocol.

Tell the agent:

```
Follow https://ascii.dev/auth.md and start a Box free trial for me.
```

That file is the contract. The agent discovers endpoints from `/.well-known/oauth-protected-resource`, registers, and only then calls the Box API.

## What the agent does

```mermaid theme={null}
sequenceDiagram
  participant Agent
  participant Box
  participant Human
  Agent->>Box: GET /auth.md and well-known metadata
  Agent->>Box: POST /agent/identity (anonymous or email)
  alt anonymous
    Box-->>Agent: identity assertion (read-only)
  else email
    Box-->>Agent: user_code + verification URL
  end
  Agent->>Human: Open this link and type this 6-digit code
  Human->>Box: Sign in, enter the code
  Box-->>Agent: access_token (Box API key)
  Agent->>Box: POST /api/box/billing/checkout
  Agent->>Human: Open Stripe Checkout to start the 7-day trial
  Human->>Box: Card + trial
  Agent->>Box: POST /api/box/v1/boxes
```

Two registration methods:

* **Anonymous** — the agent gets a token immediately. It can call `GET /me` and `GET /limits` only. Creating boxes returns `claim_required` until a human claims it.
* **Email (`service_auth`)** — the agent already knows the user's email. No token until that person signs in and types the code.

ID-JAG / provider-attested identity is not accepted yet. The agent should not send `identity_assertion` registration bodies.

## Trial

Starting a trial is the same Stripe Checkout a human uses from the dashboard. The agent calls `POST /api/box/billing/checkout` with the claimed token and shows the returned URL. Card, trial-abuse checks, and "one trial per identity" still apply. Anonymous tokens cannot start a trial.

## Endpoints

Hosted on `https://ascii.dev` (also under `/api/box/...` so they work behind the existing `/api` proxy):

| Path                                      | Purpose                             |
| ----------------------------------------- | ----------------------------------- |
| `/auth.md`                                | Agent-readable walkthrough          |
| `/.well-known/oauth-protected-resource`   | RFC 9728 discovery                  |
| `/.well-known/oauth-authorization-server` | RFC 8414 + `agent_auth` block       |
| `POST /agent/identity`                    | Register                            |
| `POST /agent/identity/claim`              | Start or refresh the claim ceremony |
| `GET /agent/identity/claim`               | Human claim page                    |
| `POST /oauth2/token`                      | Exchange assertion or poll claim    |
| `POST /oauth2/revoke`                     | Revoke one access token             |

A 401 from the Box API includes `WWW-Authenticate: Bearer resource_metadata="https://ascii.dev/api/box/.well-known/oauth-protected-resource"` so an agent that simply hits the API can find the rest.