Quickstart

This guide walks through the complete local setup: starting infrastructure, configuring environment variables, running the API, issuing a credential, and verifying it publicly. By the end you will have a working Certiva instance and a verified credential response.

You need Node.js 20+, pnpm 9+, and Docker with Docker Compose installed before starting.

Clone and install dependencies

git clone <certiva-repository-url>
cd certiva
pnpm install

Start infrastructure

docker compose up -d

This starts PostgreSQL 16 on port 5432 and Redis 7 on port 6379. Both have health checks configured — wait a few seconds before proceeding.

Configure environment variables

Copy the example files for each app:

cp .env.example .env
cp apps/api/.env.example apps/api/.env
cp apps/web/.env.example apps/web/.env
cp apps/worker/.env.example apps/worker/.env

Minimum values to set in apps/api/.env for local development:

DATABASE_URL=postgresql://certiva:certiva@localhost:5432/certiva
REDIS_URL=redis://localhost:6379
JWT_SECRET=<at-least-64-random-characters>
CORS_ORIGINS=http://localhost:3000
API_PUBLIC_BASE_URL=http://localhost:4000
WEB_PUBLIC_BASE_URL=http://localhost:3000
STORAGE_DRIVER=local
ASSET_STORAGE_ROOT=./uploads

STORAGE_DRIVER=local is only allowed in development. Staging and production require STORAGE_DRIVER=r2 with Cloudflare R2 credentials. See Configuration for the full variable reference.

Run migrations and start the API

cd apps/api
pnpm dev

Prisma migrations are applied automatically on startup via prisma migrate deploy. The API listens on port 4000 by default.Confirm it is running:

curl http://localhost:4000/api/health

{ "status": "ok" }

Start the web dashboard and worker

In two separate terminals:

# Terminal 2 — web dashboard
cd apps/web
pnpm dev

# Terminal 3 — background worker
cd apps/worker
pnpm dev

The dashboard is available at http://localhost:3000.

Seed the database and issue a credential

Create the initial Owner admin account:

cd apps/api
pnpm prisma:seed

curl -X POST http://localhost:4000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username": "admin", "password": "<seed-password>"}'

{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

The API also sets an httpOnly cookie (certiva_access_token). Browser-based dashboard requests use the cookie automatically — no manual header needed.

Issue a credential:

curl -X POST http://localhost:4000/api/credentials \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <accessToken>" \
  -d '{
    "studentName": "Ahmad Fauzi Ramadhan",
    "studentId": "2019081234",
    "degree": "Bachelor of Computer Science",
    "graduationYear": 2024
  }'

{
  "id": "clx9k2...",
  "verificationId": "vrf_2f9a0cdbe7c1",
  "verificationCode": "CERT-A1B2C3",
  "verificationUrl": "http://localhost:3000/verify/vrf_2f9a0cdbe7c1",
  "qrCodeUri": "http://localhost:4000/api/credentials/<id>/qr",
  "anchorStatus": "PENDING",
  "studentName": "Ahmad Fauzi Ramadhan",
  "studentId": "2019081234",
  "degree": "Bachelor of Computer Science",
  "graduationYear": 2024,
  "issuedAt": "2024-03-14T08:00:00.000Z"
}

anchorStatus starts as PENDING and transitions to ANCHORED after the worker processes the blockchain job. This happens asynchronously and does not block the credential from being verified immediately.

Verify the credential publicly

Anyone can verify without a Certiva account:

curl -X POST http://localhost:4000/api/verify/credential/code \
  -H "Content-Type: application/json" \
  -d '{"verificationCode": "CERT-A1B2C3"}'

{
  "verificationId": "vrf_2f9a0cdbe7c1",
  "verificationCode": "CERT-A1B2C3",
  "verificationMode": "CORE_REGISTRY",
  "valid": true,
  "result": "VALID",
  "revoked": false,
  "revocationReason": null,
  "degree": "Bachelor of Computer Science",
  "issuedAt": "2024-03-14T08:00:00.000Z",
  "issuer": {
    "name": "Universitas Contoh",
    "domain": "example.ac.id",
    "status": "ACTIVE"
  },
  "blockchainVerified": false,
  "anchorStatus": "PENDING"
}

A result of VALID confirms the credential is active and unrevoked. Once the worker anchors the credential, blockchainVerified becomes true and the response includes txHash, blockNumber, and anchoredAt.

Next steps

Concepts

Credential lifecycle, verification modes, roles, and blockchain anchoring.

Configuration

Every environment variable with validation rules and production requirements.

Workflows

Bulk issuance, revocation, document proofs, and admin management.

API Reference

All endpoints with request/response shapes.

Start here

Product guide

API reference

Next steps

Concepts

Configuration

Workflows

API Reference

​Next steps

Concepts

Configuration

Workflows

API Reference

Next steps