Skip to main content
This guide walks you through cloning the platform, starting its infrastructure, and issuing a verifiable credential via the REST API.

​
Prerequisites

Before you begin, make sure you have the following installed:
  • Docker and Docker Compose — Install Docker
  • Node.js v18.17.0 or later — Install Node.js
  • pnpm v9.15.3 or later — comes pinned in package.json
  • NestJS CLI — used to start individual microservices
npm i -g @nestjs/cli@latest
npm i -g pnpm
1

Clone and install dependencies

Clone the platform repository and install all Node.js dependencies using pnpm.
git clone https://github.com/credebl/platform.git
cd platform
pnpm install
pnpm is declared as the package manager in package.json. Using npm or yarn may result in dependency resolution issues.
2

Start infrastructure services

The docker-compose.yml at the repository root starts NATS (message broker) and Redis (cache/queues). PostgreSQL is run separately via Docker.Start PostgreSQL:
docker run --name credebl-postgres \
  -p 5432:5432 \
  -e POSTGRES_USER=credebl \
  -e POSTGRES_PASSWORD=changeme \
  -e POSTGRES_DB=credebl \
  -v credebl_pgdata:/var/lib/postgresql/data \
  -d postgres:16
Start NATS and Redis:
docker-compose up -d nats redis
The services expose the following ports:
ServicePort(s)
PostgreSQL5432
NATS4222, 6222, 8222
Redis6379
NATS is the message bus that all microservices use to communicate. It must be running before you start any service.
3

Configure environment variables

Copy the sample environment file and populate it with your local values.
cp .env.sample .env
The repository includes .env.sample with all available variables and inline comments. The API Gateway reads API_GATEWAY_PORT (defaults to 5000) and API_GATEWAY_HOST at startup, along with NATS and database connection details.
At minimum, set the following variables in your .env file:
# PostgreSQL
DATABASE_URL=postgresql://credebl:changeme@localhost:5432/credebl

# NATS
NATS_URL=nats://localhost:4222

# API Gateway
API_GATEWAY_PORT=5000
API_GATEWAY_HOST=0.0.0.0
API_GATEWAY_PROTOCOL=http

# Platform identity
PLATFORM_NAME=CREDEBL
PLATFORM_ADMIN_EMAIL=platform.admin@example.com
PLATFORM_WALLET_NAME=platform-wallet
PLATFORM_WALLET_PASSWORD=changeme
PLATFORM_SEED=101111110111101100111100000Seed1
4

Run database migrations and seed data

Generate the Prisma client and push the database schema, then seed the initial master data.
cd libs/prisma-service/prisma
npx prisma generate
npx prisma db push
Seed the initial data (ledger entries, roles, and platform defaults):
cd libs/prisma-service
npx prisma db seed
The start script in package.json also runs npx prisma migrate deploy automatically before launching the API Gateway, so in production you can use npm run start to handle migrations.
5

Start the API Gateway and microservices

Open a separate terminal window for each service. Start the API Gateway first, then bring up the remaining microservices.API Gateway (terminal 1):
nest start
For development with live-reload:
nest start --watch
Core microservices — each in its own terminal:
nest start user --watch
Start services in the order listed above. agent-service waits until agent-provisioning is listening on NATS before it initializes the platform agent wallet.
6

Access the Swagger UI

Once the API Gateway is running, open your browser and navigate to:
http://localhost:5000/api
The Swagger UI lists every available endpoint, grouped by resource. You can explore and test all APIs directly from this interface. The gateway serves API routes under URI-versioned paths (e.g., /v1/...).
Experimental OID4VC and x509 controller endpoints are hidden by default. Set HIDE_EXPERIMENTAL_OIDC_CONTROLLERS=false in your .env to expose them in the Swagger UI.
7

Register, create an organization, and issue a credential

The following sequence demonstrates the minimum steps to issue a verifiable credential: register a user, sign in, create an organization, and issue a credential over DIDComm.1. Send a verification email
curl -X POST http://localhost:5000/v1/auth/verification-mail \
  -H "Content-Type: application/json" \
  -d '{"email": "alice@example.com"}'
2. Register the user (after verifying the email link)
curl -X POST http://localhost:5000/v1/auth/signup \
  -H "Content-Type: application/json" \
  -d '{
    "email": "alice@example.com",
    "firstName": "Alice",
    "lastName": "Smith",
    "password": "Passw0rd!",
    "isEmailVerified": true
  }'
3. Sign in and capture your access token
curl -X POST http://localhost:5000/v1/auth/signin \
  -H "Content-Type: application/json" \
  -d '{"email": "alice@example.com", "password": "Passw0rd!"}' \
  | jq -r '.data.access_token'
Save the returned token as TOKEN for subsequent requests.4. Create an organization
curl -X POST http://localhost:5000/v1/orgs \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corp",
    "description": "My first CREDEBL organization"
  }'
Note the id field in the response — this is your ORG_ID.5. Issue a credential out-of-band (email delivery)
curl -X POST http://localhost:5000/v1/orgs/$ORG_ID/credentials/oob/email \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "credentialDefinitionId": "<your-cred-def-id>",
    "comment": "Your first credential",
    "attributes": [
      {"name": "firstName", "value": "Alice"},
      {"name": "lastName",  "value": "Smith"}
    ],
    "emailId": "alice@example.com"
  }'
Before issuing credentials you must create a schema and credential definition for your organization. Use the /v1/schemas and /v1/orgs/:orgId/credential-definitions endpoints visible in the Swagger UI. Your organization also needs an active Hyperledger Aries agent — provision one via the agent endpoints in Swagger.

​
Next steps

Architecture

Learn how the microservices communicate over NATS and how agents are provisioned per organization.

Environment variables

Full reference for all configuration options available in .env.

API reference

Explore every endpoint with request and response examples.

Docker Compose deployment

Run the entire platform stack — including all microservices — with a single command using pre-built images.

Build docs developers (and LLMs) love

Get started for freeTalk to us