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

# API Authentication

> All BossMode API requests authenticate with an operator token. Here's how to get one, use it, and rotate it.

<Warning>🚧 Expanding soon — full Authentication documentation is in progress.</Warning>

## Operator token

Every Pro account gets an operator token. This token authenticates all API requests and associates them with your operator account.

**Token format:** `bm_live_••••••••••••••••••••••••••••••`

### Getting your token

1. Sign up at [bossmode.ing/signup](https://bossmode.ing/signup)
2. Go to **Settings → API Token**
3. Copy your token

### Using your token

Pass the token in the `x-bossmode-token` header on every request:

```bash theme={null}
curl -sH "x-bossmode-token: $BOSSMODE_API_TOKEN" \
  https://bossmode.ing/api/pro/context
```

Never pass the token as a query parameter — it will appear in server logs.

### Storing your token safely

```bash theme={null}
# Add to .env.local (gitignored)
echo "BOSSMODE_API_TOKEN=bm_live_your_token" >> .env.local

# Or export for the session
export BOSSMODE_API_TOKEN=bm_live_your_token
```

Never commit your token to a repository. Never log it. Never embed it in client-side code.

## Token rotation

```bash theme={null}
curl -sX POST https://bossmode.ing/api/pro/tokens/rotate \
  -H "x-bossmode-token: $BOSSMODE_API_TOKEN"
```

Rotation immediately invalidates the old token and returns a new one. Update your environment variables before the old token expires (60 second grace period).

## Service-to-service calls

For internal service-to-service calls (e.g., from your own server to BossMode), use the `BOSSMODE_SERVICE_KEY` environment variable. This key bypasses rate limits and is not tied to a single operator account.

Contact support for service key provisioning.

## Token scopes

Future versions will support scoped tokens with fine-grained permissions. For now, all tokens have full operator access.

## Errors

| Status | Code           | Description                              |
| ------ | -------------- | ---------------------------------------- |
| 401    | `UNAUTHORIZED` | Token missing or invalid                 |
| 403    | `FORBIDDEN`    | Token valid but insufficient permissions |
| 429    | `RATE_LIMITED` | Exceeded rate limit for your tier        |