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, multimodal /v1/ingest, and the /v1/audit routes, and quota_exceeded once the document ceiling (25k) or the namespace count (1) is hit. Planes outside a tier are silently clamped out of search. See Pricing & billing for the full gating matrix and the upgrade flow.

Sign-up & auto-provisioning#

A brand-new console account does not land in the shared demo tenant. On first authenticated request a session with no linked principal is auto-provisioned its own namespace (slug u-<email>-<id>), an owner grant (read, write, admin on all scopes), and a starter registry scope default/main. So a new user can read and write / upload immediately, on a scope they actually own — never stranded read-only on someone else’s data. Provisioning is idempotent and runs once per user.

Multi-namespace tenancy#

A principal may own more than one namespace (for example one per company). Listing and creating the namespaces you own is self-service — it is not a control-plane admin operation:

• GET /v1/namespaces returns your home namespace plus any namespace you hold a grant on (an auto-provisioned home with no registry row is synthesized in, so your workspace switcher always shows it).
• POST /v1/namespaces registers/claims a namespace. Claiming an unclaimed namespace re-homes you into it as owner on first onboarding; once your home has scopes, creating another namespace grants you ownership without moving your home.
• Creating a new namespace counts against the tier’s max_namespaces quota (Free = 1, Pro/Enterprise = unlimited) → 402 quota_exceeded when exceeded.

Select which namespace a request runs against with the X-Aegis-Namespace header. Targeting a namespace you were not granted is a hard 403 — tenant isolation is preserved. (Grants and principals CRUD remain admin-gated.)

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
}

Per-user API keys#

Beyond the seeded demo tokens, SuperChargeDB is gaining per-user API keys: a signed-in console user will be able to mint, name, and revoke their own aegis_sk_… bearer tokens, scoped to their principal, from the console. A minted key authenticates exactly like any bearer token above and inherits the same grants, scope clamp, and ACL — so a key can never do more than the user who created it. Use per-user keys to authenticate the SDK, CLI, and MCP server for a specific human instead of sharing a token.

Auth errors#

• 401 unauthorized — missing or invalid bearer token / no resolvable session.
• 403 forbidden — authenticated but lacking the required permission (e.g. write/admin), or targeting a namespace you were not granted.
• 402 upgrade_required / 402 quota_exceeded — the action or volume exceeds your tier.