Skip to main content

HTTP and auth

This page defines request headers and retry contracts.

Required headers​

All requests:

  • X-Realm-Id: <realm_id>

Write requests:

  • Idempotency-Key: <key>

Account context (varies by endpoint):

  • X-Principal-Id: <principal_id> and/or
  • X-Billing-Account-Id: <billing_account_id>

Tracing:

  • X-Request-Id: <request_id> (recommended)

Optional admin header:

  • X-Realm-Admin: true (enables realm admin RLS for authorized callers)

Authentication​

Service-to-service (S2S)​

Use Service Key authentication for /mgt/v1 endpoints. See OpenAPI security scheme serviceAuth for details.

Bearer (end-user)​

Use bearer tokens for /api/v1 endpoints where bearerAuth is allowed.

Content digest​

Some S2S endpoints require:

  • Content-Digest: sha-256=:<base64_sha256_of_raw_body_bytes>:

Follow OpenAPI requirements for exact behavior.

Idempotency semantics​

  • Same route and idempotency key with the same logical request replays the first success.
  • Reusing the same key with a different request body returns a conflict.

Status codes (common)​

  • 200: success or idempotent replay
  • 201: created
  • 207: multi-status for batch operations
  • 409: idempotency conflict
  • 422: validation failed
  • 429: rate limited