# auth.md

Sign your person up for Prized and get an API key: one call with their email address, one with the 6-digit code Prized emails them. This makes NEW accounts only; if they already use Prized, they make a key at https://prized.dev/dashboard/workspace/api-keys instead. People read https://prized.dev/docs/agent-sign-in.

## Rules

- Only for the person you work for, when they ask, with their own address.
- Get the code from them. Never ask anyone else for it, never guess it: five tries end it.
- The key is a credential. Never print, commit or log it. Keep it where your person says. For CLI storage, follow Use the key below; never put the key in process arguments or shell command strings.
- Never quote a price, credit or runway from memory. Read them (Prices, below).
- Call https://api.prized.dev exactly as written here. Keep the explicit `--url` when logging in: it is the API that issued this key, not the web origin or a previously configured control plane.

## 1. Sign up

```http
POST https://api.prized.dev/api/v1/agent/sign-up
Content-Type: application/json

{"email": "maya@yourcompany.com", "name": "Claude Code", "personName": "Maya Lopez"}
```

- `name` (optional): what you are called, letters and spaces only, up to 40. This is a self-reported key label, not a verified identity. The code email never displays it and warns that Prized has not verified which app made the request.
- `personName` (optional): your person's name, if you know it. The new account is named after it.

The answer is `{"key": "dcp_…", "verified": false, "codeExpiresAt": "…", …}`, the same whether or not the address has an account. Tell your person:

> Prized emailed you a 6-digit code. Please give it to me.

Until then the key can call only `GET /api/v1/me`; everything else answers `403 verification_required`. While that code is live (15 minutes), signing up again for the address answers `409 code_pending`: keep the key you have. After it lapses, signing up again gives a new key and code (the old key answers `key_replaced`), at most five codes a day per inbox.

## 2. Verify

```http
POST https://api.prized.dev/api/v1/agent/verify
Authorization: Bearer <key>
Content-Type: application/json

{"code": "123456"}
```

```json
{
  "verified": true,
  "key": {"name": "Agent: Claude Code", "access": {"boxes": "write", "sandboxes": "write", "secrets": "none", "workspace": "read"}, "expiresAt": "…"},
  "workspace": {"id": "…", "name": "…"},
  "freeCredit": true,
  "billingUrl": "https://prized.dev/dashboard/billing"
}
```

The account now exists, in a workspace of its own, and the key works. `freeCredit` says whether this call granted the free credit (one per inbox). If the address already had an account, the answer is `409 sign_in_required` and no key is made.

## 3. Use the key

To save the verified key for the CLI, use your process runner to execute `prized login --url https://api.prized.dev --token-stdin` and write the key plus a newline directly to the child's stdin, then close stdin. Keep the key out of process arguments, shell command strings (including inline scripts and here-documents), environment variables, and tool logs. Do not fall back to passing it as an argument: on Linux, other local processes may read arguments through `/proc/<pid>/cmdline`. If your tool cannot supply stdin without logging it, ask your person to run the interactive CLI login instead.

`Authorization: Bearer <key>` on `https://api.prized.dev/api/v1`; the reference is https://prized.dev/docs/api.md.

- It can start, stop and use boxes and sandboxes and read the workspace; secrets answer `403 key_access_denied`. Never work around a refusal; ask your person.
- It works for 90 days. After that your person makes a new one at https://prized.dev/dashboard/workspace/api-keys (the account exists now, so signing up again answers `sign_in_required`).
- `POST /api/v1/boxes` with `{}` starts a Small (`202`; poll `GET /api/v1/boxes/<id>` until `observedState` is `running`). No credit, or a larger size, needs a plan (`insufficient_balance`, `409 tier_unavailable`): send your person `billingUrl`.
- `POST /api/v1/sandboxes?wait=running` with `{"template": "prized-agent-v1"}` starts a sandbox (`201`). The calls to copy files in, run commands, fork, pause and delete are at https://prized.dev/docs/sandboxes-agent-quickstart.md, every route at https://prized.dev/docs/sandboxes-api.md. On the free credit it runs within the free tier (https://prized.dev/docs/sandboxes#free-tier): past it, `429 sandbox_quota_exceeded` or `422 invalid_resources` with `"tier": "free"`, and `409 paid_balance_required` means sandboxes need money paid in. Delete sandboxes you are done with; for more, send your person `billingUrl`. Each sandbox you create is on your person's audit log.

## Prices

Read them, never recall them: https://prized.dev/pricing.md (every box size and sandbox rate) and https://prized.dev/docs/billing.md for prices; `billing` in `GET /api/v1/me` for the balance and runway. Refusals carry their numbers in micro-dollars (`1000000` is $1).

## Revoke

`DELETE https://api.prized.dev/api/v1/agent/key` with the key as bearer: `204`, and it stops working. Your person can also revoke it at https://prized.dev/dashboard/workspace/api-keys.

## Errors

| Code | What to do |
| --- | --- |
| `invalid_email`, `invalid_name`, `invalid_person_name` | Fix the field. |
| `email_not_allowed` | Placeholder or throwaway domain: use your person's real address. |
| `code_pending` | A code for this address is live: verify with your key, or wait until `codeExpiresAt`. |
| `rate_limited` | Wait for `Retry-After`. |
| `mail_unavailable` | The code was not sent. Try again in a minute. |
| `verification_required` | Verify the key first. |
| `invalid_code` | Send the 6 digits. |
| `code_mismatch` | Ask your person to check it; `triesLeft` says what is left. |
| `code_expired` | Sign up again for a new code, and verify with the new key. |
| `key_replaced` | A later sign-up replaced this key: sign up again. |
| `already_verified` | The key works. Use it. |
| `sign_in_required` | The address already has an account: your person makes a key at https://prized.dev/dashboard/workspace/api-keys. |
| `account_unavailable` | Ask your person to sign in at https://prized.dev. |
| `unauthorized` | Send the key sign-up returned as the bearer. |