# Token Management

Atomic server uses named, revocable API tokens stored as SHA-256 hashes. Raw token values are shown only once when created.

## When You Need Tokens

- The desktop app creates and manages its local sidecar token automatically.
- Self-hosted web users need a token after the instance is claimed.
- The iOS app needs a token.
- The browser extension needs a token.
- MCP clients connected over HTTP need a token.
- Scripts and direct API calls need a token.

Use a separate token per device or integration so you can revoke one without disrupting others.

## First Token

Fresh self-hosted instances can be claimed through the setup UI. The public setup endpoints only work while there are no active tokens:

```
curl http://localhost:8080/api/setup/status

curl -X POST http://localhost:8080/api/setup/claim \

-H "Content-Type: application/json" \

-d '{"name": "admin"}'
```

After an instance has active tokens, `claim` returns a conflict.

## CLI Commands

For SQLite:

```
atomic-server --data-dir ./data token create --name "my-laptop"

atomic-server --data-dir ./data token list

atomic-server --data-dir ./data token revoke <token-id>
```

When running from source:

```
cargo run -p atomic-server -- --data-dir ./data token create --name "my-laptop"
```

For Postgres, use the same storage environment variables as the server:

```
ATOMIC_STORAGE=postgres \

ATOMIC_DATABASE_URL=postgres://user:pass@host:5432/atomic \

atomic-server token list
```

## API Endpoints

Create token:

```
curl -X POST http://localhost:8080/api/auth/tokens \

-H "Authorization: Bearer <admin-token>" \

-H "Content-Type: application/json" \

-d '{"name": "new-token"}'
```

List tokens:

```
curl http://localhost:8080/api/auth/tokens \

-H "Authorization: Bearer <admin-token>"
```

Revoke token:

```
curl -X DELETE http://localhost:8080/api/auth/tokens/<token-id> \

-H "Authorization: Bearer <admin-token>"
```

## Usage

Include the token in the `Authorization` header:

```
Authorization: Bearer <your-token>
```

WebSocket clients pass the token in the query string:

```
ws://localhost:8080/ws?token=<your-token>
```

## Security Notes

- Save newly created tokens immediately. Atomic stores only a hash and cannot show the raw token again.
- Revoke stale or leaked tokens.
- Prefer HTTPS for remote deployments.
- Use separate tokens for iOS, browser extension, MCP, and scripts.