SharkAuth API — Admin Endpoints

All admin endpoints require an admin API key passed as a Bearer token:

The key is written to data/admin.key.firstboot at first boot and is available via GET /api/v1/admin/firstboot/key until the admin account is bootstrapped. All responses use the extended error envelope {error, code, message, docs_url, details}.

Health & System

GET /api/v1/admin/health

Returns server health including DB status, JWT config, SMTP provider, uptime, active signing keys, SSO connection count, and applied migration version.

Response 200:

{
  "status": "ok",
  "version": "0.9.0",
  "uptime_seconds": 3600,
  "db": { "driver": "sqlite3", "size_mb": 2.4, "status": "ok" },
  "migrations": { "current": 42, "name": "add_proxy_rules" },
  "jwt": { "mode": "asymmetric", "algorithm": "ES256", "active_keys": 1 },
  "smtp": { "tier": "dev", "configured": true, "sent_today": 3, "daily_limit": 100 },
  "oauth_providers": ["google", "github"],
  "sso_connections": 0
}

GET /healthz — Liveness probe (no auth)

{ "status": "ok" }

Returns 503 with { "status": "unhealthy", "error": "database unreachable" } when the DB ping fails.

GET /api/v1/admin/stats

Aggregate dashboard statistics (user count, active sessions, agent count, etc.).

GET /api/v1/admin/stats/trends

Time-series trends for the dashboard stats chart.

GET /api/v1/admin/config / PATCH /api/v1/admin/config

Read or update the runtime configuration stored in the database. Replaces the deprecated YAML config surface (W17).

GET /api/v1/admin/system/mode

Returns the current server mode (dev / production).

POST /api/v1/admin/system/swap-mode

Swaps between dev and production mode. Triggers a drain + re-init cycle.

POST /api/v1/admin/system/reset

Hard-resets all runtime state (sessions, tokens, audit logs). Requires explicit confirmation body. Useful in dev/test.

POST /api/v1/admin/auth/rotate-signing-key

Rotates the JWT signing key. Old key is retired (kept in JWKS for 2× token TTL). Subsequent tokens are signed with the new key.

POST /api/v1/admin/auth/revoke-jti

Revokes a specific JWT by JTI (JWT ID). Useful for immediate admin-forced logout of a single token.

Request:

{ "jti": "01HZ2XKA..." }

Bootstrap & First Boot

GET /api/v1/admin/firstboot/key

Returns the admin API key from first boot. Public — returns 404 once the admin account has been bootstrapped. Intended for automated provisioning scripts.

Response 200:

{ "key": "sk_live_abc123..." }

POST /api/v1/admin/bootstrap/consume

Consumes the one-time bootstrap token to set up the first admin account. The token in the request body is the credential — no Authorization header needed.

Request:

{ "token": "<bootstrap-token>", "email": "admin@example.com", "password": "..." }

GET /api/v1/admin/bootstrap/status

Returns whether the server has been bootstrapped (admin account created).

Users

Base path: /api/v1/users Auth: Admin API key

Example — Get user:

{
  "id": "usr_01HZ2XKABCDEF",
  "email": "alice@example.com",
  "email_verified": true,
  "name": "Alice Example",
  "mfa_enabled": false,
  "created_at": "2024-04-01T10:00:00Z"
}

Tier management (proxy paywall gating):

PATCH /api/v1/admin/users/{id}/tier — Set user tier for proxy paywall rules.

{ "tier": "pro" }

Agents

Base path: /api/v1/agents Auth: Admin API key

Agents are machine-to-machine OAuth clients registered via the admin API (distinct from DCR which is protocol-level).

Example — Create agent request:

{
  "client_name": "my-billing-agent",
  "grant_types": ["client_credentials", "urn:ietf:params:oauth:grant-type:token-exchange"],
  "scope": "openid billing:read",
  "token_endpoint_auth_method": "client_secret_basic"
}

Response 201 (client_secret shown once):

{
  "id": "agt_01HZ2XKABCDEF",
  "client_id": "shark_dcr_abc123",
  "client_secret": "cs_live_...",
  "client_name": "my-billing-agent",
  "grant_types": ["client_credentials"],
  "scope": "openid billing:read",
  "active": true,
  "dpop_bound": false,
  "created_at": "2024-04-01T10:00:00Z"
}

Applications

Base path: /api/v1/admin/apps Auth: Admin API key

Applications represent OAuth clients used by web/mobile frontends.

Audit Logs

Base path: /api/v1/audit-logs Auth: Admin API key

Query parameters for list:

• actor_type — filter by actor type (user, admin, agent)
• action — filter by action name (e.g. user.created)
• from / to — ISO 8601 date range
• limit / cursor — keyset pagination

Example event:

{
  "id": "al_01HZ2XKABCDEF",
  "actor_type": "admin",
  "actor_id": "admin_key",
  "action": "user.deleted",
  "target_type": "user",
  "target_id": "usr_01HZ2XKABCDEF",
  "metadata": {},
  "created_at": "2024-04-01T10:05:00Z"
}

Vault (Token Vault)

Base path: /api/v1/vault Auth: Admin API key (providers), Session cookie (user flows), Bearer token (agent retrieval)

Client secrets are never returned after creation — rotation goes through the PATCH body field.

Auth Flows (Flow Builder)

Base path: /api/v1/admin/flows Auth: Admin API key

Auth flows are custom trigger-based pipelines that run at signup, login, password-reset, magic-link, and OAuth callback events.

Supported triggers: signup, login, password_reset, magic_link, oauth_callback

Supported step types: require_email_verification, require_mfa_enrollment, require_mfa_challenge, require_password_strength, redirect, webhook, set_metadata, assign_role, add_to_org, custom_check, delay, conditional

Example — Create flow:

{
  "name": "Require MFA on login",
  "trigger": "login",
  "enabled": true,
  "priority": 10,
  "steps": [
    { "type": "require_mfa_enrollment", "config": {} },
    { "type": "require_mfa_challenge", "config": {} }
  ]
}

Webhooks

Base path: /api/v1/webhooks Auth: Admin API key

See 03-webhooks.md for the full webhook documentation including signature verification, event catalogue, and retry behavior.

Email Config & Dev Inbox

GET /api/v1/admin/email-config / PATCH /api/v1/admin/email-config

Read or update email redirect URL configuration (post-verification redirect, password-reset links, etc.).

POST /api/v1/admin/test-email

Send a test email using the currently configured provider.

GET /api/v1/admin/email-preview/{template}

Preview a rendered email template.

GET /api/v1/admin/dev/emails

List captured dev-mode emails (only functional when email provider is dev). Useful for local testing without an SMTP server.

GET /api/v1/admin/dev/emails/{id}

Get a specific dev email.

DELETE /api/v1/admin/dev/emails

Delete all captured dev emails.

Email Templates

Base path: /api/v1/admin/email-templates Auth: Admin API key

Branding

Base path: /api/v1/admin/branding Auth: Admin API key

Branding assets (logos) are served publicly at /assets/branding/* — content-addressed, immutable-cached.

Sessions (Admin)

Base path: /api/v1/admin/sessions Auth: Admin API key

Roles & Permissions (Admin RBAC)

Auth: Admin API key

Organizations (Admin)

Base path: /api/v1/admin/organizations Auth: Admin API key

OAuth Consents (Admin)

Proxy (Reverse Proxy Admin)

Base path: /api/v1/admin/proxy Auth: Admin API key

These endpoints return 404 when the proxy is disabled at boot.

SSO Connections (Admin)

Base path: /api/v1/sso/connections Auth: Admin API key

Public SSO endpoints (no auth):

• GET /api/v1/sso/saml/{connection_id}/metadata — SAML SP metadata XML
• POST /api/v1/sso/saml/{connection_id}/acs — SAML ACS (Assertion Consumer Service)
• GET /api/v1/sso/oidc/{connection_id}/auth — OIDC authorization redirect
• GET /api/v1/sso/oidc/{connection_id}/callback — OIDC callback

API Keys (Admin)

Base path: /api/v1/api-keys Auth: Admin API key

Admin Logs