API Keys - Esheria

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.

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.

Create A Token In The Dashboard

Open https://dashboard.esheria.ai/.
Sign up or sign in.
Open API Tokens.
Create a data token with a clear name such as Production backend or Local development.
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:

esheria tokens create --name "Monitoring operator" \
  --scope regulatory:read --scope monitoring:write \
  --pack UK-DATA-USE-AND-ACCESS

Local Setup

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

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.

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

Create a new data token in the dashboard.
Deploy the new key to services and MCP hosts.
Run esheria packs list --format json.
Revoke the old key from API Tokens.
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

​Create A Token In The Dashboard

​Local Setup

​Test A Key

​CLI Configuration

​Rotation Checklist

​Common Failure Modes

Create A Token In The Dashboard

Local Setup

Test A Key

CLI Configuration

Rotation Checklist

Common Failure Modes