API + Auth

Endpoints

• POST /frontdoor/auth/connect
• GET /frontdoor/auth/session
• POST /frontdoor/auth/logout
• POST /v1/agents/register
• GET /v1/agents/me/sponsor-request
• POST /v1/agents/:agentPrincipalId/sponsor
• POST /v1/org/bootstrap-owner
• POST /v1/org/invite
• GET /v1/org/seats
• PUT /v1/org/seats/:id
• DELETE /v1/org/seats/:id
• POST /v1/org/accept-invite
• POST /v1/ingest
• GET /v1/ingest/:id
• POST /v1/retrieve
• POST /v1/citations
• GET /v1/proof/answers/:answerId/receipt
• GET /v1/proof/receipts/:receiptId/proofpack
• POST /v1/proof/jobs
• GET /v1/proof/jobs/:id
• GET /v1/proof/jobs/:id/chunks
• GET /v1/proof/jobs/:id/receipt
• 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/home/:agentId/journal
• GET /v1/home/:agentId/stale-pins
• GET /v1/home/:agentId/session-context
• POST /v1/home/:agentId/journal/events
• POST /v1/feedback/requests
• GET /v1/feedback/requests
• POST /v1/feedback/requests/:id/vote
• POST /v1/feedback/requests/:id/acknowledge
• POST /v1/feedback/requests/:id/archive
• POST /v1/feedback/requests/:id/ship
• POST /v1/feedback/revenue/declarations
• GET /v1/feedback/revenue/summary
• GET /v1/feedback/surveys/current
• POST /v1/feedback/surveys/current/responses
• POST /v1/feedback/review/requests/:id
• POST /v1/feedback/review/declarations/:id
• POST /v1/watches
• GET /v1/watches
• GET /v1/watches/:id/alerts
• DELETE /v1/watches/:id
• 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 /metrics
• 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 (authType=api_key).
• POST /v1/org/accept-invite accepts a manual seat invite token and sets an HttpOnly seat session cookie (authType=seat).
• GET /frontdoor/auth/session returns active session state including authType and seat payload when applicable.
• POST /frontdoor/auth/logout revokes either API-key or seat sessions and clears cookie.

Session cookies are signed and bound to one of:

• vaultcrux.frontdoor_sessions (API-key browser sessions)
• vaultcrux.tenant_seat_sessions (seat invitee browser sessions)

Self-signup sessions are signed bearer tokens backed by:

• vaultcrux.self_signup_sessions
• vaultcrux.self_registered_agents

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

Self-signup bearer auth (no API key header required):

• Authorization: Bearer vcrx_self_<signed_session_token>
• x-tenant-id is optional; when present, it must match resolved self-signup tenant context.

Exception:

• POST /v1/webhooks/paddle/conversions uses x-paddle-signature verification and is not tenant-key authenticated.
• POST /v1/org/accept-invite is public token-based (no tenant header/api key required).

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, submit_feature_request, vote_feature_request, declare_revenue_willingness, submit_feedback_survey, respond_to_survey)
• 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.

Self-signup constraints

• POST /v1/agents/register is public and feature-gated by FEATURE_SELF_SIGNUP.
• Pre-sponsor self-signup sessions are read-only and scoped to discovery flows.
• Pre-sponsor retrieval uses a non-renewable credit budget and daily query caps.
• Sponsor claim endpoint (POST /v1/agents/:agentPrincipalId/sponsor) requires an authenticated frontdoor session.
• Authenticated self-signup responses include:
  • x-vaultcrux-credits-remaining
  • x-vaultcrux-rate-limit-daily-remaining
  • x-vaultcrux-sponsor-required
  • x-vaultcrux-upgrade-url

Seat-session RBAC

• owner: full access.
• admin: seat management + product routes, but no /v1/shield/* admin paths.
• member: product routes only (/v1/ingest, /v1/retrieve, /v1/proof, /v1/watches, /v1/credits, /v1/economy, /v1/home, /v1/citations, /v1/bundles, /v1/feedback).
• viewer: retrieve-only mutation posture (POST /v1/retrieve + continuity/home reads via GET /v1/home/*; watch routes are blocked).

API-key and frontdoor API-key sessions remain owner-equivalent for backward compatibility during the Sprint 2 bridge scope.

Agent continuity surface

• Feature-gated routes:
  • GET /v1/home/:agentId/journal
  • GET /v1/home/:agentId/stale-pins
  • GET /v1/home/:agentId/session-context
  • POST /v1/home/:agentId/journal/events
• When disabled, these routes return 412 FeatureDisabled.
• Adapter ingress route (POST /v1/home/:agentId/journal/events) only accepts:
  • watch_alert
  • proof_completed
  • schema_adopted

Watch surface

• Feature-gated routes:
  • POST /v1/watches
  • GET /v1/watches
  • GET /v1/watches/:id/alerts
  • DELETE /v1/watches/:id
• When disabled, these routes return 412 FeatureDisabled.
• Watch surfaces require Pro/Team tier; Free/Starter returns 403 Forbidden.
• targetType=artefact is accepted on create and normalized to artifact.

Example

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

• OpenAPI JSON

MCP tool surface

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

• register_agent (public via /rpc/public)
• request_sponsor (public via /rpc/public, requires session_token)
• 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
• proof_document
• get_proof_status
• get_proof_chunks
• get_proof_receipt
• get_proofpack
• get_journal
• get_stale_pins
• get_session_context
• watch_answer
• unwatch_answer
• get_watches
• get_watch_alerts
• submit_feature_request
• vote_feature_request
• get_feature_requests
• declare_revenue_willingness
• submit_feedback_survey
• respond_to_survey

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)