Reference Implementation
The blerify-verification-demo is a deployable reference implementation of the Blerify verification integration pattern. It's a Next.js server-side application that demonstrates the complete flow: authenticating a service account, starting a verification session, showing the user a QR code or wallet button, and polling for the result. No secrets leave the server.
Use it as a working example to understand the integration before building your own, or fork it as a starting point for a real deployment.
The source is at github.com/BlerifyPlatform/blerify-verification-demo. Build instructions, local development setup, and the full source live in that repository's README — this page covers the portal prerequisites, configuration, and deployment targets.
Prerequisites
A Blerify account with owner or organization admin access
A verification project in the Portal
The two portal artifacts described below: a service account and a published verification template
How it works
The demo is a Backend For Frontend (BFF). Your browser never holds credentials or calls Blerify directly.
Browser ──POST /api/start──▶ BFF ──start session──▶ Blerify
│ shows QR or wallet button ◀── { transaction_id, ... }
│
Wallet ── scans QR or opens deep link, presents credential ──▶ Blerify
│
└─ GET /api/status?transactionId ──▶ BFF ──poll result──▶ Blerify
◀── { status, credential claims }The BFF authenticates to Blerify using a service account with private_key_jwt (RFC 7523). The wallet talks to Blerify directly — the BFF is never in the credential transport path. The result comes back by polling, keyed on transaction_id.
On mobile, the demo detects the user agent and shows a wallet button instead of a QR code. A toggle lets users switch to QR if their wallet is on a different device.
For the full protocol detail — endpoints, request/response schemas, session states — see the Verification API Reference.
Step 1 — Create a service account
The service account is how the BFF authenticates to Blerify machine-to-machine. You create it at the organization level and need owner or organization admin access.
In the Portal, go to Organization → Service Accounts and click Create service account.
Fill in a name and description.
Under Signing algorithm, select
RS256.Under Roles, select Verifications — this grants the account permission to start and poll verification sessions.
Under Project, choose the verification project where your template lives (or will live).
Click Create. The Portal generates a key pair and prompts you to download a JSON credentials file.
Download the file now. The private key is shown once and cannot be retrieved again. The download button stays active until you close the dialog — close it only after saving the file.
The downloaded JSON contains everything the demo needs to authenticate:
client_id
SA_CLIENT_ID
private_key
SA_PRIVATE_KEY
iam_audience
SA_IAM_AUDIENCE
token_uri
SA_TOKEN_URI (optional)
organization_id
SA_ORGANIZATION_ID (optional)
Step 2 — Create and publish a verification template
A verification template defines what credential to request, which issuer to trust, and what assurance level to require. It lives inside a verification project.
Open the verification project and go to Verification Rules → New rule.
Choose an assurance level and the credential types to accept. This opens a five-step wizard:
Information — name, internal code, description, type
Attributes and proofs — which claims to request from each credential
Verifications — validation settings and transport (OpenID4VP)
Sanction lists — optional control lists
Technical integration — select the service account you created in Step 1, then generate the rule ID
In the Technical integration step, click Generate ID to save the rule as a draft, then click Publish rule to activate it. Only a published rule can be used at runtime.
Finding your IDs. The Technical integration step shows a code snippet with the full endpoint path. That path contains all three IDs you need:
Copy them from there. RULE_ID is the UUID labeled Rule ID in the integration step — not the ver_… identifier shown on the rule detail screen.
Step 3 — Configure the demo
All configuration is runtime — nothing is baked into the build artifact. Copy .env.example from the repository and set the values for your environment:
BLERIFY_API_URL
Blerify API base URL for your environment
ORG_ID
Your organization ID
PROJECT_ID
Your verification project ID
RULE_ID
The UUID of your published verification template
WALLET_BASE_URL
Base URL of the Blerify Wallet
SA_CLIENT_ID
From the service account JSON
SA_PRIVATE_KEY
From the service account JSON (PEM, PKCS#8, RSA-2048)
SA_IAM_AUDIENCE
From the service account JSON
SA_TOKEN_URI
Optional — defaults to the standard token endpoint
SA_ORGANIZATION_ID
Optional — defaults to ORG_ID
DEMO_MOCK
Set to true to run the full UI without a real backend or service account
DEMO_MOCK=true lets you explore the UI and simulate the complete flow without configuring any Blerify credentials. Use it to evaluate the interface before setting up the Portal prerequisites.
Deploying
The same codebase deploys to three targets. In every case, set environment variables in the platform — never commit them to the repository.
Netlify
Connect the repository in the Netlify dashboard. The netlify.toml in the repo declares the build command and configures the Next.js adapter, which serves the API routes as serverless functions. Set environment variables under Site settings → Environment variables.
Vercel
Import the repository in the Vercel dashboard. Vercel auto-detects it as a Next.js project using vercel.json. Set environment variables in the project settings.
Docker
The image is generic — it reads all configuration from environment variables at startup. Use the same image across environments by changing the env file, not the image.
The repository's CI pipeline validates every push: type-checking, build, and Docker image construction. It does not deploy and requires no secrets.
Next steps
Continue to Verify from a Web App — the complete guide for building your own verification UI from scratch, covering all three presentation scenarios, the full result schema, and error handling.
See also: Get Started with a Verification · Assurance Tiers · API Reference
Last updated