export const metadata = {
  title: "Authentication: SEO Insight Docs",
  description:
    "How API keys, Bearer tokens and workspace scopes work in the SEO Insight API.",
};

# Authentication

The SEO Insight API uses **API keys** sent as a Bearer token. Every request must
include an `Authorization` header.

```bash
curl https://api.seoinsight.app/v1/keywords \
  -H "Authorization: Bearer $SEO_INSIGHT_API_KEY"
```

## Key types

- **Live keys** (`sk_live_…`) act on real workspace data.
- **Test keys** (`sk_test_…`) act on an isolated sandbox, safe for development.

## Scopes

Each key is scoped to a single workspace and a permission level:

| Scope        | Reservoir | Backlinks | Content briefs |
| ------------ | --------- | --------- | -------------- |
| `read`       | read      | read      | read           |
| `read_write` | read      | read      | create / edit  |

Give agents the narrowest scope they need. A read-only key is enough for
querying quick-wins; a read-write key is required to generate and save briefs.

## Rotating keys

Rotate a key from **Settings → API keys**. Old keys keep working for a short
grace window so you can roll deployments without downtime, then revoke them.

> Never commit keys to source control. Use environment variables or a secrets
> manager, and prefer test keys in local development.