# Authentication

REST and MCP authenticate with a workspace-bound bearer token:

```bash
Authorization: Bearer ingram_live_…
```

## Getting a token

**Programmatically** — `POST /api/v1/accounts` creates user + workspace +
token in one call (see the [Quickstart](/docs/quickstart)). Optional fields:
`token_name` labels the token; `prefund` charges a payment method and credits
the wallet in the same call, so an agent is ready to spend immediately.

**Dashboard** — **Settings → API tokens → New token**. Pick the scope; the
token is displayed once.

## Scopes

| Scope | Grants |
|---|---|
| `read` | Availability checks, pricing, listing domains, domain details, DNS reads |
| `write` | Everything in `read`, plus mutations: register/renew/transfer, DNS changes, security toggles, deletes |

Give agents the narrowest scope that works. A read token cannot spend money
under any circumstances.

## Handling

- Tokens are stored **hashed** server-side — lost tokens cannot be recovered,
  only revoked and re-minted (Settings → API tokens).
- The prefix (`ingram_live_3fk…`) is shown in listings so you can tell tokens
  apart without ever seeing the secret again.
- Requests without a valid token get `401 missing_token` /
  `401 invalid_token` in the standard [error envelope](/docs/errors).
- Public endpoints (`/check`, `/suggest`, `/tlds` pricing via check) need no
  token.

## Dashboard sign-in

The dashboard itself uses session auth (email + password or Google), separate
from API tokens. Password reset and email verification are built in. Sessions
never authenticate `/api/v1` — only bearer tokens do.