VaultCrux Docs

Appearance

API + Auth ​

Endpoints ​

  • POST /frontdoor/auth/connect
  • GET /frontdoor/auth/session
  • POST /frontdoor/auth/logout
  • POST /v1/ingest
  • GET /v1/ingest/:id
  • POST /v1/retrieve
  • POST /v1/citations
  • GET /v1/credits/:agentId
  • GET /v1/credits/:agentId/escrow
  • GET /v1/economy/dashboard/:agentId
  • POST /v1/economy/convert/preview
  • POST /v1/economy/convert
  • POST /v1/economy/tip-platform
  • POST /v1/webhooks/paddle/conversions
  • GET /v1/bundles
  • POST /v1/bundles/purchase
  • GET /v1/home/:agentId/primitives
  • POST /v1/home/:agentId/primitives
  • GET /v1/shield/capabilities
  • GET /v1/shield/trust/publishers
  • POST /v1/shield/trust/publishers
  • GET /v1/shield/trust/digests
  • POST /v1/shield/trust/digests
  • POST /v1/shield/trust/digests/revoke
  • GET /v1/shield/servers
  • POST /v1/shield/servers
  • POST /v1/shield/servers/:serverId/status
  • POST /v1/shield/approvals/propose
  • POST /v1/shield/approvals/:approvalRequestId/resolve
  • GET /v1/shield/approvals/:approvalRequestId
  • GET /v1/shield/kill-switches
  • POST /v1/shield/kill-switches
  • DELETE /v1/shield/kill-switches/:killSwitchId
  • GET /v1/shield/sampling-policies
  • POST /v1/shield/sampling-policies
  • GET /v1/shield/ui-integrity-sessions
  • POST /v1/shield/ui-integrity-sessions
  • GET /v1/shield/incident-drills
  • POST /v1/shield/incident-drills
  • GET /healthz
  • GET /readyz
  • GET /build-info

Authentication model ​

VaultCrux uses tenant-scoped API keys persisted in vaultcrux.api_keys.

Frontdoor uses same-origin session auth:

  • POST /frontdoor/auth/connect validates tenant + API key, then sets an HttpOnly session cookie.
  • GET /frontdoor/auth/session returns active session state.
  • POST /frontdoor/auth/logout revokes current session and clears cookie.

Session cookies are signed and bound to vaultcrux.frontdoor_sessions rows.

Canonical request headers for /v1/*:

  • x-tenant-id
  • x-api-key
  • x-idempotency-key for mutation calls
  • x-shield-approval-token for approved shield-gated mutation calls

Exception:

  • POST /v1/webhooks/paddle/conversions uses x-paddle-signature verification and is not tenant-key authenticated.

Canonical request headers for MCP /rpc, /stream, /sse, and /capabilities:

  • x-tenant-id
  • x-api-key
  • x-idempotency-key for mutating tools (tip_platform, convert_credits_to_discount, purchase_bundle)
  • x-shield-approval-token when approval workflow returns an approval token

Header-first compatibility window ​

  • Production (NODE_ENV=production): x-tenant-id and x-api-key are required.
  • Exception for Frontdoor runtime: when valid frontdoor session cookie is present, /v1/* accepts cookie-backed auth without sending x-api-key from the browser.
  • Non-production: legacy tenant values in body/query are temporarily allowed when ALLOW_LEGACY_TENANT_FIELDS=true.
  • If header tenant and body/query tenant disagree, API returns 403 Forbidden.
  • For POST /v1/retrieve and POST /v1/citations, tenantId in body is optional when tenant context is already resolved by header/session auth.

Example ​

bash
curl -X POST http://localhost:14333/v1/retrieve \
  -H "content-type: application/json" \
  -H "x-tenant-id: tenant-a" \
  -H "x-api-key: example-key" \
  -d '{
    "query": "How do we keep replay handlers idempotent?",
    "limit": 5,
    "lane": "audit"
  }'

OpenAPI ​

Generated from VaultCrux/apps/api:

bash
cd ../VaultCrux
pnpm openapi:emit
cd ../VaultCrux-Docs
pnpm sync:openapi

MCP tool surface ​

VaultCrux/apps/mcp exposes JSON-RPC 2.0 methods:

  • query_vault
  • get_credit_balance
  • get_credit_escrow
  • get_economy_dashboard
  • convert_credits_to_discount
  • get_subscription_discount_preview
  • tip_platform
  • browse_bundles
  • purchase_bundle

Transport options:

  • POST /rpc for standard JSON-RPC request/response
  • POST /stream for streamable HTTP (application/x-ndjson)
  • GET /sse for SSE capability/heartbeat stream
  • stdio bridge (pnpm --filter @vaultcrux/mcp stdio)

Copyright 2026 CueCrux