Skip to content
Wholisphere Docs

Authentication

The Wholisphere API supports two authentication mechanisms.

API keys are issued per-organization from the dashboard.

Format: whk_<32 alphanumeric characters> (44 chars total).

Send via header:

x-api-key: whk_aBcDeFgHiJkLmNoPqRsTuVwXyZ123456

Keys are SHA-256 hashed at rest. The plaintext is shown to you exactly once at creation — record it now.

Rotate (revoke + re-issue) at any time from the dashboard. Revoked keys stop working immediately.

Session cookies (dashboard only)

The dashboard uses an HTTP-only whs_session cookie set by the magic-link sign-in flow. You shouldn’t need to touch this directly — it’s managed by the dashboard’s UI.

  1. POST /v1/auth/request with { "email": "you@example.com" }
  2. We email a one-time link valid for 15 minutes
  3. The link redirects through /v1/auth/callback?token=... which sets the cookie and redirects to the dashboard

In dev (no Resend key configured), the magic link is logged to backend stderr and returned in the response body as devLink for direct copy-paste.

Legacy: install-id (deprecated)

The v1 dashboard issues a UUID per-install (“install ID”) that’s accepted as x-install-id. New integrations should use API keys instead. Install IDs will continue to work through 2026 for backwards compat.

Permissions

API keys have scopes:

  • agent:rw — full agent surface (default)
  • agent:r — read-only (telemetry, audit, vpat)
  • cache:invalidate — only the cache invalidation route (issue this for CI bots)

Scopes are enforced at the route level. Issue narrow scopes for narrow purposes.

Rotating + revoking

Terminal window
# List keys
curl https://api.wholisphere.ai/v1/orgs/$ORG_ID/keys \
  -H "cookie: whs_session=$SESSION"


# Create
curl -X POST https://api.wholisphere.ai/v1/orgs/$ORG_ID/keys \
  -H "cookie: whs_session=$SESSION" \
  -H 'content-type: application/json' \
  -d '{"name":"GitHub Action prod","scopes":["cache:invalidate"]}'
# → returns plaintext ONCE — store it now


# Revoke
curl -X POST https://api.wholisphere.ai/v1/orgs/$ORG_ID/keys/$KEY_ID/revoke \
  -H "cookie: whs_session=$SESSION"