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

# API Keys

> Store, rotate, and test Esheria API keys without leaking credentials.

API keys identify the client calling the Regulatory Pack API. Treat keys as production credentials.

Create API tokens from the Esheria API Dashboard at
`https://dashboard.esheria.ai/`. The dashboard creates workspace-scoped data
tokens for production services, local development, CLI use, and MCP hosts.
Store tokens in your shell for local testing or in your service secret manager
for production use.

Dashboard-created and OAuth connector tokens are read-only
(`regulatory:read`). A workspace owner can use a management token to create a
least-privilege operator data token with `monitoring:write`, `graph:write`, or
`customer:write` when an integration must change hosted state.

<Info>
  Existing customers may also receive a workspace token from an Esheria
  operator or workspace owner. Dashboard-created data tokens are the recommended
  self-serve path for new integrations.
</Info>

## Create A Token In The Dashboard

1. Open `https://dashboard.esheria.ai/`.
2. Sign up or sign in.
3. Open **API Tokens**.
4. Create a data token with a clear name such as `Production backend` or `Local development`.
5. Store the returned token secret immediately. It is shown once and cannot be recovered later.

Use separate data tokens for each service, environment, and major integration.
That makes revocation and usage debugging easier.

For an operator token, repeat the CLI `--scope` option. Unknown scopes and
management scopes are rejected for data tokens:

```bash theme={null}
esheria tokens create --name "Monitoring operator" \
  --scope regulatory:read --scope monitoring:write \
  --pack UK-DATA-USE-AND-ACCESS
```

## Local Setup

```bash theme={null}
export ESHERIA_API_BASE_URL="https://api.esheria.ai"
export ESHERIA_API_KEY="YOUR_DASHBOARD_CREATED_DATA_TOKEN"
export ESHERIA_DEFAULT_PACK_ID="EU-NIS2-CYBERSECURITY"
```

`ESHERIA_DEFAULT_PACK_ID` is an optional client preference chosen by you; it is
not a server-side jurisdiction default. Pack-specific commands still accept an
explicit pack ID.

For long-running services, store keys in the host secret manager and inject them as environment variables at runtime.

## Test A Key

```bash theme={null}
curl --compressed -sS \
  "$ESHERIA_API_BASE_URL/api/v1/domain-packs?limit=1" \
  -H "x-api-key: $ESHERIA_API_KEY" | jq
```

A valid key returns `status: ok`. An invalid key returns the normal error envelope with `unauthorized`.

## CLI Configuration

The CLI reads the same environment variables.

```bash theme={null}
esheria doctor --pack "$ESHERIA_DEFAULT_PACK_ID" --format json
```

The CLI redacts credential status in diagnostics. It should report whether a key is `set` or `missing`, never the key value.

## Rotation Checklist

1. Create a new data token in the dashboard.
2. Deploy the new key to services and MCP hosts.
3. Run `esheria packs list --format json`.
4. Revoke the old key from **API Tokens**.
5. Remove exposed key material from shell history, logs, and screenshots.

## Common Failure Modes

| Symptom                               | Cause                                                       | Resolution                                                      |
| ------------------------------------- | ----------------------------------------------------------- | --------------------------------------------------------------- |
| Works in one terminal but not another | Environment variable was exported only in one shell         | Re-export the key or use your shell profile carefully           |
| CLI calls SSH or another command      | A local alias shadows `esheria`                             | Run `type -a esheria` and remove the alias                      |
| Browser playground fails on pilot URL | HTTPS docs page calling an HTTP pilot server can be blocked | Use the production HTTPS base URL for browser-based playgrounds |