Authentication

Protected endpoints require an API key in the x-api-key header.

x-api-key: YOUR_ESHERIA_API_KEY

Create self-serve API tokens from https://dashboard.esheria.ai/. Dashboard signup requires a verified Google or GitHub email, resolves your workspace, and lets you choose plan-allowed packs before creating/revoking data tokens. Public email/password signup is not enabled in production. GET /healthz and GET /readyz are operational endpoints. Regulatory pack endpoints under /api/v1 require authentication. In billing-enabled workspaces, API keys are workspace tokens. Management tokens can create and revoke data tokens and read billing state. Dashboard-created and OAuth connector data tokens use regulatory:read by default. Hosted-state mutations require an explicitly created operator data token with monitoring:write, graph:write, or customer:write; read scope alone is rejected. Data-token requests are charged against workspace credits. The dashboard uses server-side management credentials for token, billing, workspace, checkout, and playground operations. Do not put management tokens or dashboard server credentials in browser applications.

Mutating Requests

All mutating requests require an idempotency key. This applies to POST workflows such as claim verification, applicability checks, and graph applicability checks.

idempotency-key: unique-request-intent

Use a stable key for a single request intent. Reusing the same key with the same payload allows replay protection; reusing it with a different payload returns a conflict. Authentication and current scope/pack/feature authorization run before replay, and stored responses are isolated by workspace and token.

Trace IDs

Every response includes a trace_id.

{
  "status": "ok",
  "data": {},
  "errors": [],
  "trace_id": "bdf7825f-..."
}

Store trace_id with user-visible decisions, support tickets, and agent outputs. It is the fastest way to connect a downstream answer to the API request that produced it.

Example

curl --compressed -sS -X POST \
  "$ESHERIA_API_BASE_URL/api/v1/domain-packs/UK-DATA-PROTECTION-PRIVACY/applicability-check" \
  -H "content-type: application/json" \
  -H "x-api-key: $ESHERIA_API_KEY" \
  -H "idempotency-key: applicability-$(date +%s)" \
  -d '{
    "entity_profile": {
      "jurisdictions": ["UK"],
      "entity_types": ["data_controller"],
      "regulated_activities": ["personal_data_processing"],
      "data_categories": ["customer_personal_data"]
    },
    "profile_facts": [],
    "limit": 5
  }' | jq

Failure Modes

Code	Meaning	Action
`unauthorized`	The API key is missing or invalid	Check the header and rotate any exposed key
`forbidden`	The token lacks the required read/write scope or pack entitlement	Use a correctly scoped least-privilege token
`credits_exhausted`	The workspace has no available credits	Add credits or create a Stripe Checkout top-up
`billing_unavailable`	The billing ledger could not be checked	Retry after operators restore ledger availability
`idempotency_key_required`	A mutating request was sent without `idempotency-key`	Generate a unique key for the request intent
`idempotency_key_conflict`	The same key was reused with a different payload	Use a new key or replay the original payload
`validation_error`	Request fields did not match the API schema	Compare the payload with the API Reference

Do not put API keys in docs, repositories, browser screenshots, support tickets, agent transcripts, or browser bundles. Use the dashboard token list and trace_id values for debugging instead of raw token secrets.

Overview

Core guides

Mutating Requests

Trace IDs

Example

Failure Modes

​Mutating Requests

​Trace IDs

​Example

​Failure Modes

Mutating Requests

Trace IDs

Example

Failure Modes