> For the complete documentation index, see [llms.txt](https://docs.blerify.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.blerify.com/introduction-to-verification/reference/reference-implementation.md).

# 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](https://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 [API Reference](https://dev.blerify.com).

***

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

```
.../organizations/{ORG_ID}/projects/{PROJECT_ID}/verifications/{RULE_ID}
```

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

```bash
docker build -t blerify-verification-demo .
docker run --env-file .env -p 8080:8080 blerify-verification-demo
```

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** [**Get Started**](/introduction-to-verification/build/get-started.md) — build the same flow this demo implements, step by step.

See also: [Read a Verification Result](/introduction-to-verification/build/read-a-verification-result.md) · [Assurance Tiers](/introduction-to-verification/learn/assurance-tiers.md) · [API Reference](https://dev.blerify.com)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.blerify.com/introduction-to-verification/reference/reference-implementation.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.