Skip to main content

Getting Started

You will have a working authorization request running locally before the end of this guide.

Veritrellis evaluates a policy, returns a signed permit when the action is allowed, and requires you to verify that permit before your code executes the action. No valid permit, no execution.

Prerequisites​

Requirements
  • Node.js 22 or later
  • pnpm 9 or later
  • Docker (recommended) or a local PostgreSQL instance
  • A WorkOS account for admin authentication

1. Install and boot the stack​

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

pnpm seed prints a workspace ID and a sandbox API key. Keep those — you will use them in the next step.

Expected output

After pnpm seed you will see something like:

Workspace: ws_01HXXX...
API key:   vt_sandbox_01HYYY...

2. Send your first authorization request​

Paste the values from pnpm seed into the request below:

Terminal
curl -sS http://localhost:3001/v1/authorize \
  -H "Authorization: Bearer YOUR_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": "EUR",
      "reason": "customer request"
    }
  }'

What to expect​

The seeded policy grants refunds up to €100 directly and requires human approval above that threshold:

AmountDecisionResponse includes
<= 100allowedpermit JWT
> 100pending_approvalrequest_id for polling

A direct-allow response looks like this:

Response — allowed
{
  "decision": "allowed",
  "request_id": "req_01HXXX...",
  "permit": "eyJhbGciOiJFUzI1NiJ9..."
}

3. Verify the permit before executing​

Never skip this step. A permit that cannot be verified should halt execution.

verify.ts
import { verifyPermit } from "@veritrellis/sdk-node";

const claims = await verifyPermit({
  permitJwt: result.permit,
  workspaceId: process.env.VERITRELLIS_WORKSPACE_ID!,
  issuer: "https://api.veritrellis.ai"
});

// claims.action_type === "issue_refund"
// claims.sub       === "req_01HXXX..."
// Execute your action here — only when claims are valid

verifyPermit checks the signature via the workspace JWKS endpoint, validates the issuer, confirms audience context, and rejects expired permits. It throws on any verification failure.

4. Handle a pending-approval response​

When decision is pending_approval, poll until the request resolves:

Terminal
curl -sS "http://localhost:3001/v1/permits/REQUEST_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"
Status codeMeaning
200Approved — response includes permit
202Still waiting for approval
409Terminal state with no permit (denied or expired)

5. Open the admin app​

http://127.0.0.1:3000 — complete onboarding to create a workspace, review policies, approve pending requests, and inspect audit events.

Sandbox vs. production

The seeded workspace runs in the sandbox environment. All behavior is identical to production except that permit JWTs are issued against sandbox JWKS. Keep environment: "sandbox" in your API requests while testing.

Next steps​