Getting Started

Integrate Veritrellis into your application: run the control plane locally, configure environments and API keys, and complete your first authorization request.

Prerequisites

• Node 22+
• pnpm 9+
• Docker (recommended) or local PostgreSQL
• WorkOS account for admin authentication

Local setup

pnpm install
pnpm docker:up
pnpm docker:wait
pnpm db:migrate
pnpm seed
pnpm dev

Environment configuration

Use the templates below and keep values aligned between API and admin server:

• Root: .env.example
• API: apps/api/.env.example
• Admin server: apps/admin-server/.env.example

Critical settings:

• APP_MASTER_KEY must be base64 for exactly 32 bytes (openssl rand -base64 32)
• WORKOS_COOKIE_PASSWORD must match in API and admin server
• API_ORIGIN should match where your clients call the API

First authorize call

Use the workspace/API key printed by pnpm seed.

curl -sS http://localhost:3001/v1/authorize \
  -H "Authorization: Bearer API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "environment":"sandbox",
    "action_type":"issue_refund",
    "resource_ref":"cus_123",
    "payload":{
      "customer_id":"cus_123",
      "amount":50,
      "currency":"USD",
      "reason":"customer request"
    }
  }'

Expected result with seeded policy:

• allowed and a permit for amounts <= 100
• pending_approval for larger amounts
• denied when policy rules reject

Permit polling

For pending requests:

curl -sS "http://localhost:3001/v1/permits/REQUEST_ID" \
  -H "Authorization: Bearer API_KEY"

• 202 while approval is pending
• 200 with permit after approval
• 409 for terminal non-permit outcomes

Admin app

Open http://127.0.0.1:3000 (or your configured ADMIN_PUBLIC_ORIGIN) and complete onboarding:

• Create workspace
• Review policies
• Check requests, approvals, and audit events

Next steps

• API contracts: /api/overview
• Node SDK usage: /sdk/node
• Connector guides: /connectors/hubspot