For the complete documentation index, see llms.txt. This page is also available as Markdown.

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.

  1. In the Portal, go to Organization → Service Accounts and click Create service account.

  2. Fill in a name and description.

  3. Under Signing algorithm, select RS256.

  4. Under Roles, select Verifications — this grants the account permission to start and poll verification sessions.

  5. Under Project, choose the verification project where your template lives (or will live).

  6. Click Create. The Portal generates a key pair and prompts you to download a JSON credentials file.

  7. 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:

JSON field
Environment variable

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.

  1. Open the verification project and go to Verification Rules → New rule.

  2. 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

  3. 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:

Variable
Description

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