# Macro Scout — authentication (agent)

Parent brief: https://docs.macrocontent.dev/scout.md  
OpenAPI: https://api.scout.macrocontent.dev/openapi.json

## Headers

Every `/v1` route needs a Scout API key:

```http
Authorization: Bearer sk_scout_…
# or
X-Scout-Key: sk_scout_…
```

```bash
curl https://api.scout.macrocontent.dev/v1/usage \
  -H "Authorization: Bearer sk_scout_…"
```

## Keys

- Form: `sk_scout_…`
- Account-scoped credit wallet (shared across keys on the account)
- Rate limit follows tier (Free ~30/min, Basic ~120/min, Pro ~250/min)
- **Server secrets only** — never put in frontend bundles or public repos

## Errors

| Code | Meaning |
|------|---------|
| `402 CREDITS_EXHAUSTED` | Prepaid empty and PAYG off |
| `429 RATE_LIMITED` | Requests/min exceeded (retryable) |

Tiers & packs: https://docs.macrocontent.dev/scout/tiers/  
Swagger Authorize: https://api.scout.macrocontent.dev/docs/