Authentication

Authentication mechanisms#

The API resolves a principal from the first mechanism present, in this order:

Bearer tokens#

Pass an API token in the Authorization header. Tokens are stored as SHA-256 hashes; an invalid token is a hard 401.

curl -s "https://superchargedb.krisch1218.workers.dev/v1/context" \
  -H "Authorization: Bearer aegis_sk_alice"

Seeded test principals#

The demo namespace acme-corp is seeded with two principals that make access control observable:

Because Bob lacks the finance group and the frontend scope, he sees strictly fewer Units than Alice — the basis for the ACL and scope examples throughout these docs.

Per-tier test credentials#

Each subscription tier is seeded as its own namespace (≈ a separate database) with a token whose access is clamped to that tier’s limits. These are identical on local and production — both come from POST /v1/admin/seed.

A request that exceeds a tier’s limits returns 402: the Free tier gets upgrade_required for /v1/answer and /v1/audit, and quota_exceeded once the document ceiling is hit. Planes outside a tier are silently clamped out of search.

Super-admin (all databases)#

aegis_sk_root is a cross-namespace super-admin. It reaches every namespace, bypasses per-hit ACL, and is never coerced read-only. Select the target namespace with the X-Aegis-Namespace header (it defaults to acme-corp when omitted).

# Inspect the Pro tenant as root
curl -s "https://superchargedb.krisch1218.workers.dev/v1/context" \
  -H "Authorization: Bearer aegis_sk_root" \
  -H "X-Aegis-Namespace: pro-tenant"

# Read every unit in the enterprise tenant (ACL ignored)
curl -s "https://superchargedb.krisch1218.workers.dev/v1/units?limit=100" \
  -H "Authorization: Bearer aegis_sk_root" \
  -H "X-Aegis-Namespace: ent-tenant"

Selecting a scope#

Scope is the project partition your request runs against. It is not taken from the request body — set it with the X-Aegis-Scope header or the ?scope= query parameter. If omitted, the principal’s active scope is used. The special value * expands to every scope the principal is allowed (it never widens access).

# Header form
curl -s -X POST "https://superchargedb.krisch1218.workers.dev/v1/search" \
  -H "Authorization: Bearer aegis_sk_alice" \
  -H "X-Aegis-Scope: acme/alpha/frontend" \
  -H "Content-Type: application/json" \
  -d '{"q":"roadmap dashboard"}'

# Query-param form (search across all allowed scopes)
curl -s -X POST "https://superchargedb.krisch1218.workers.dev/v1/search?scope=*" \
  -H "Authorization: Bearer aegis_sk_alice" \
  -H "Content-Type: application/json" \
  -d '{"q":"roadmap dashboard"}'

Inspect your resolved access

GET /v1/context returns exactly what the engine computed for your principal + scope: effective scopes, allowed scopes, and permissions.

{
  "principal": { "principal_id": "alice@acme", "namespace": "acme-corp", "read_only": false,
    "groups": ["eng-backend", "eng", "finance"] },
  "active_scope": "acme/alpha/backend",
  "requested_scope": "acme/alpha/backend",
  "effective_scopes": ["acme/alpha/backend"],
  "allowed_scopes": ["acme/alpha/backend", "acme/alpha/frontend"],
  "perms": ["read", "write", "admin"],
  "folders_visible": 2,
  "folders_total": 2
}

Auth errors#

• 401 unauthorized — missing or invalid bearer token / no resolvable session.
• 403 forbidden — authenticated but lacking the required permission (e.g. write/admin).