# Ample Computer auth.md

How an AI agent or automated client obtains and uses an Ample Computer credential. Everything here is self-serve: no browser, CAPTCHA or payment is needed for a first deployment. Canonical URL: https://ample.computer/auth.md. Last updated 2026-11-05.

## Discover

Start from the machine-readable documents rather than scraping:

- OAuth protected resource metadata (RFC 9728), published by the resource server: https://api.ample.computer/.well-known/oauth-protected-resource for the REST API and https://api.ample.computer/.well-known/oauth-protected-resource/mcp for the MCP resource. Each names the authorization server `https://api.ample.computer`, the supported scopes and `header` bearer tokens.
- OAuth authorization server metadata (RFC 8414): https://api.ample.computer/.well-known/oauth-authorization-server. Its `agent_auth` block points back to this file (`skill`), gives the registration endpoint (`register_uri`: https://api.ample.computer/v1/auth/signup) and the claim page (`claim_uri`: https://ample.computer/claim), and lists one registration method: `anonymous`, issuing an `access_token` and OAuth `client_credentials`. The same document lists the browser endpoints for hosts where a person signs in (see "Connect an account from an app host").
- API catalog (RFC 9727): https://ample.computer/.well-known/api-catalog
- OpenAPI description: https://ample.computer/openapi.json
- MCP setup guide: https://api.ample.computer/mcp/setup

The `agent_auth` field names follow the Auth.md discovery recipe that agent-readiness scanners check (`register_uri`, `claim_uri`). The request and response bodies are Ample Computer's own and are described below.

An unauthenticated request to `https://api.ample.computer/mcp` returns `401` with a JSON body `{"error":{"code":"authentication_required","message":"..."}}`.

## Pick a method

| You are | Use | Credential |
| --- | --- | --- |
| A coding agent in the user's terminal (Claude Code, Codex, Cursor) | Remote MCP at `https://api.ample.computer/mcp`, connected once by the person (https://ample.computer/agents); the Ample Computer CLI if they would rather not | OAuth 2.1 authorization code with PKCE (an email code); for the CLI, the local login written by `ample auth signup` or `ample auth login` |
| An agent host or editor without a local install | Remote MCP at `https://api.ample.computer/mcp` | OAuth 2.0 client credentials from `POST /v1/auth/signup` |
| An app host where a person connects their account (ChatGPT, Claude, Codex on the web) | Remote MCP at `https://api.ample.computer/mcp` | OAuth 2.1 authorization code with PKCE; the person signs in at `https://api.ample.computer/oauth/authorize` |
| Another agent speaking A2A | A2A at `https://api.ample.computer/a2a` (card: https://api.ample.computer/.well-known/agent-card.json) | The same credentials; the `ample_auth_signup` skill registers without any |
| A script or CI job | REST API | Scoped bearer token from `ample auth token create` or an agent credential |
| A sub-agent acting inside an account | Agent credential | `ample auth agent create --scope ...`; secret shown once |

If you are an AI agent working in the user's terminal, ask the person to connect the MCP server (one command and an email sign-in): the account is theirs from the start. If they would rather not, or nobody is there to answer, use the CLI.

## Register

```sh
curl -fsSL https://get.ample.computer/install.sh | sh
ample auth signup          # creates an account and stores the login locally
```

Or without the CLI:

```sh
curl -X POST https://api.ample.computer/v1/auth/signup \
  -H 'Content-Type: application/json' \
  -d '{"name":"my-agent","request_key":"<fresh UUID v4>"}'
```

Generate and save the `request_key` before sending. Re-sending the same key within ten minutes returns the same registration receipt, so a disconnected client never creates a second account. The response carries the account identity, a claim URL, the fixed account expiry, an `access_token` and `credentials.client_id` / `client_secret`.

### With a connect code

When a signed-in person copies their prompt from ample.computer, it carries a connect code (`ample_connect_...`). Send it with the signup and you get credentials on the person's own account instead of a new one: no claim URL, no expiry, nothing for them to do.

```sh
curl -X POST https://api.ample.computer/v1/auth/signup \
  -H 'Content-Type: application/json' \
  -d '{"name":"my-agent","request_key":"<fresh UUID v4>","connect_code":"ample_connect_..."}'
```

The CLI is `ample auth signup --connect-code <code>`, and the MCP tool `ample_auth_signup` takes `connect_code`. A code works once, for an hour; re-sending it with the same `request_key` within ten minutes returns the same answer. An expired or used code answers 400 (`connect_code_expired`, `connect_code_used`): ask the person for a fresh prompt, or sign up without one and give them the claim URL. The person sees the credential in their account's agent list and can revoke it there.

Give the person the claim URL (in the signup response and in every deploy result until the account is claimed) or the app's URL so they can keep the account: either page asks for their email and the 6-digit code Ample Computer sends, and the account becomes theirs. Unclaimed accounts expire after 48 hours; renewing tokens never extends that. Keep your credentials: once the account is claimed, everything you deploy with them is theirs, with nothing more to claim.

If the person never saw the claim URL, ask for their email and have Ample Computer send it:

```sh
curl -X POST https://api.ample.computer/v1/auth/claim \
  -H 'Authorization: Bearer <access_token>' \
  -H 'Content-Type: application/json' \
  -d '{"email":"person@example.com"}'
```

The CLI equivalent is `ample auth claim --email person@example.com`, and the MCP tool is `ample_auth_claim`. The person must open the emailed link within 30 minutes. Ample Computer never returns a link it emailed, so only the owner of that address can accept it. At most five claim emails per account, and three per address, per hour.

## Connect an account from an app host

Hosts that link a person's account, rather than letting an agent provision its own, use the authorization-code flow with PKCE (`S256` only). An agent never needs it.

- Client: an HTTPS client ID metadata document (`client_id_metadata_document_supported`), or a client registered with `POST https://api.ample.computer/oauth/register` (RFC 7591): a public client (`token_endpoint_auth_method` `none`) or a confidential client (`client_secret_basic` or `client_secret_post`; its secret is returned once, at registration). Redirect URIs are HTTPS, or HTTP to a loopback address.
- Authorize: send the person to `https://api.ample.computer/oauth/authorize` with `response_type=code`, `client_id`, `redirect_uri`, `state`, `code_challenge`, `code_challenge_method=S256` and `resource=https://api.ample.computer/mcp`. They sign in with a code Ample Computer emails them (a new email gets a free account) and approve. The redirect carries `code`, `state` and `iss` (RFC 9207).
- Token: `POST https://api.ample.computer/oauth/token` with `grant_type=authorization_code`, `code`, `code_verifier`, `client_id` and `redirect_uri`. The response adds a `refresh_token`. For a public client, `grant_type=refresh_token` rotates it on every use, and presenting a rotated one again revokes the grant. A confidential client sends its secret on every token and revocation request and keeps the same refresh token; each refresh extends it by 90 days.
- The grant appears in `ample auth agent list` under the client's name; `ample auth agent revoke`, or `POST https://api.ample.computer/oauth/revoke` with the refresh token or an access token, ends it.

## Renew

```sh
curl -X POST https://api.ample.computer/oauth/token \
  -d grant_type=client_credentials \
  -d client_id=<issued client id> \
  -d client_secret=<issued secret> \
  -d resource=https://api.ample.computer/mcp
```

HTTP Basic client authentication is also accepted. Access tokens last at most 15 minutes and are bound to the resource. Send `Authorization: Bearer <access_token>` on every protected REST or MCP request.

## Scopes

- `servers:read`: Read servers, apps, deployments, logs and operations
- `servers:write`: Create, deploy, pause, resume and destroy servers and apps
- `servers:exec`: Run commands and transfer files on a server
- `volumes:*`: Manage persistent volumes
- `databases:*`: Manage managed databases
- `buckets:*`: Manage object storage buckets and credentials
- `email:*`: Manage app email, send messages and read delivery records
- `tokens:*`: Manage API tokens and agent credentials
- `budgets:read`: Read budget status

Request the smallest set that covers the job. Operator and admin tokens are rejected by remote MCP.

## Revoke

- `DELETE https://api.ample.computer/v1/auth/tokens/{id}` revokes an API token.
- `DELETE https://api.ample.computer/v1/auth/agents/{id}` (or `ample auth agent revoke`) revokes an agent credential together with every access token and descendant credential derived from it.

## Errors

Errors are JSON: `{"error":{"code":"<snake_case_code>","message":"<human readable>"}}`. `401` means the token is missing, expired or revoked; `403` means the credential lacks a required scope; `409` means a quota, budget or busy resource blocked the request and the message names it.
