> ## 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.

# Authentication

> Use API keys, idempotency keys, and trace IDs safely across Esheria API workflows.

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

```http theme={null}
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.

```http theme={null}
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`.

```json theme={null}
{
  "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

```bash theme={null}
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        |

<Warning>
  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.
</Warning>