verifier-plus is a Next.js application providing two related, but fundamentally separate services:
-
Credential Verification and Display - A web page for viewing and verifying Verifiable Credentials.
-
Online Credential Storage - server storage for Verifiable Credentials, to enable sharing a public link for a credential.
Note
verifier-plus upports versions 1 and 2 of Verifiable Credentials, including version 3 of Open Badges, but NOT version 2 of Open Badges.
Tip
The Digital Credentials Consortium runs an instance of this application at verifierplus.org, but anyone is free to run their own instance elsewhere.
Let's talk a bit about the two services: credential verification and credential storage.
The landing page of VerifierPlus provides options for copy/pasting, uploading, linking to, or scanning a QR for a Verifiable Credential. VerifierPlus displays a nicely formatted human-readable version of a credential, verifies the credential, and displays the results of verification.
The key idea with Verifiable Credentials is that we can on-the-spot check the cryptographic signature of a Verifiable Credential to confirm that the credential hasn't been tampered with since it was signed. A full explanation of all that this entails is available in the Verifiable Credentials Specification.
Beyond the signature itself, we check a few other things, like that the credential hasn't expired, hasn't been revoked, and that it was in fact signed by a known issuer. A good place to read more about what we specificially check is our verifier-core repository which handles the underlying verification for both VerifierPlus and the Learner Credential Wallet.
We've pre-generated some sample credentials here that you can play with in our running instance of VerifierPlus.
Each credential on the samples page has a QR that you can scan from VerifierPlus, a url that you can paste into the VerifierPlus text box, or the raw JSON that you can also paste into the VerifierPlus text box.
Here is one such credential to get you started. We've provided four options for opening it in VerifierPlus:
- Open directly in VerifierPlus:
- Scan QR from VerifierPlus:
- Copy this link (which is the same link as in the QR) and paste it into the VerifierPlus text box:
4. Click here to see copyable raw json that you can copy/paste into VerifierPlus
{
"@context": [
"https://www.w3.org/ns/credentials/v2",
"https://purl.imsglobal.org/spec/ob/v3p0/context-3.0.3.json",
"https://w3id.org/security/suites/ed25519-2020/v1"
],
"id": "http://example.com/credentials/3527",
"type": [
"VerifiableCredential",
"OpenBadgeCredential"
],
"issuer": {
"id": "did:key:z6MknNQD1WHLGGraFi6zcbGevuAgkVfdyCdtZnQTGWVVvR5Q",
"type": [
"Profile"
],
"name": "Example Corp"
},
"validFrom": "2010-01-01T00:00:00Z",
"name": "Teamwork Badge",
"credentialSubject": {
"id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
"type": [
"AchievementSubject"
],
"achievement": {
"id": "https://example.com/achievements/21st-century-skills/teamwork",
"type": [
"Achievement"
],
"criteria": {
"narrative": "Team members are nominated for this badge by their peers and recognized upon review by Example Corp management."
},
"description": "This badge recognizes the development of the capacity to collaborate within a group environment.",
"name": "Teamwork"
}
},
"proof": {
"type": "Ed25519Signature2020",
"created": "2025-01-09T17:58:33Z",
"verificationMethod": "did:key:z6MknNQD1WHLGGraFi6zcbGevuAgkVfdyCdtZnQTGWVVvR5Q#z6MknNQD1WHLGGraFi6zcbGevuAgkVfdyCdtZnQTGWVVvR5Q",
"proofPurpose": "assertionMethod",
"proofValue": "z62t6TYCERpTKuWCRhHc2fV7JoMhiFuEcCXGkX9iit8atQPhviN5cZeZfXRnvJWa3Bm6DjagKyrauaSJfp9C9i7q3"
}
}You may well be wondering why anyone would ever want to deal with raw JSON code, and indeed that brings us to the second service that VerifierPlus provides:
A fundamental idea behind Verifiable Credentials is that they are standalone, autonomous, cryptographically signed declarations of some fact or facts. Verifiable Credentials are most simply just standard text (even the cryptographic signature is plain text), usually stored in files that the holder of the credential (like say a student with a Verifiable Credential copy of their degree) takes away with them and can keep forever, storing them wherever they like, without any dependency on the original issuer.
Most notably, the credentials do not have to be stored on a public server owned by an issuer (or a company acting on behalf of the issuer), and verification of the credentials can happen anywhere, anytime, without needing to make a call back to the original issuer or to any kind of online service that the issuer provides. This affords the credential holder significantly increased privacy, control and long-term ownership of their own credentials than if the credential verification runs back to the issuer.
However, because the credentials themselves are files, it can be difficult to manage them, and to share them with other people. So we usually encourage people to store their credentials in a so-called 'wallet' like our Learner Credential Wallet which consolidates the credentials in one place, in an app built specifically to help with things like receiving credentials, viewing credentials, verifying credentials, and sharing credentials.
From within a wallet we can email, text message, AirDrop/QuickShare credentials, but even then it can be confusing for the receipient to know what to do with the file: how to view it and how to verify it. They can certainly do what we've described above and upload the file to VerifierPlus, but that takes some degree of understanding, and effort, and things can go wrong. During the copy/pasting for example, characters might get moved that affect the signature. And furthermore, we might even want to share our credendial more publicly with the world, which we of course can't feasibly do with email or text messages.
One answer to all of this is of course to put the file somewhere from which it can be publicly downloaded, like DropBox, Google Drive, Github, or really anywhere that provides a public link to the file, and then we can share that link widely, even posting it to our say our LinkedIn profile. But sharing files this way can be annoying to get the permissions right, to know how to upload a file, and for many people it's just not viable.
Furthermore when we share the link to the file, whoever downloads it still has to know what to do with it, which can of course be a significant problem. Imagine, for example, if we are asked to upload proof of graduation to an online portal when say applying for a job. Whoever later reviews our application may well not know what to make of a file with JSON code in it.
Our approach, therefore, has been to provide a storage service for credentials that makes it easy to upload the credential directly from the Learner Credential Wallet, and at the same time generates a link for the credential that doesn't just return the credential, but opens the credential directly in VerifierPlus, instantly displaying and verifying the credential. The recipient of such a link doesn't see the JSON code at all, just the nicely formatted view of the credential and its verification details.
The Learner Credential Wallet also provides options making it easy to share that link with others either through email, messages, a QR code, or even by posting it to one's LinkedIn profile.
The storage service itself is simply three API endpoints for storing, retrieving, and deleting a credential. You can find them in the /app/api/credentials/route.ts file.
The api endpoints save to a credential store, which you choose with the CREDENTIAL_STORE setting: MongoDB (see MongoDB), Amazon DynamoDB (see AWS Lambda), or, for local development and tests only, the server's memory. A shared credential stays viewable for a year (CREDENTIAL_TTL_DAYS), and can be at most 350 KB.
When storing a credential with an intial POST of the credential to /api/credentials the server will put the credential into the store and return a list of three urls, like so:
{
"url": {
// human-readable HTML view of the credential
"view": "/credentials/{publicCredentialId}",
// raw JSON GET (used by the html view)
"get": "/api/credentials/{publicCredentialId}",
// used for DELETE/unshare API
"unshare": "/api/credentials/{publicCredentialId}"
}
}The raw JSON for the credential can then be retrieved using the 'get', or removed from public view with 'unshare'. The 'view' url can be used to open the credential directly in VerifierPlus, where it will be verified and displayed in a nicely formatted view.
Worth noting is that the same effect as the 'view' url can be achieved with a credential that is stored somewhere else, simply by creating a url like so:
https://verifierplus.org/#verify?vc=https://github.com/digitalcredentials/vc-test-fixtures/raw/refs/heads/main/verifiableCredentials/v2/ed25519/didKey/legacy-noStatus-noExpiry.json
VerifierPlus knows to go fetch the credential, verify it, and display it in the rendered view.
verifier-plus is configured by environment variables. settings.contract.json lists every one the app reads, and a unit test keeps it in step with the code. The ones you set:
| Setting | Required | Purpose |
|---|---|---|
CREDENTIAL_STORE |
always | memory, mongodb or dynamodb. memory loses every shared credential on restart: local development and tests only. |
EXCHANGES |
always | on or off: whether the landing page can request credentials from the Learner Credential Wallet. See below. |
EXCHANGE_SERVER_URL |
no | Where wallets reach the exchange, when exchanges are on. Defaults to the address the browser used to reach the page. |
CREDENTIAL_TTL_DAYS |
no | How many days a shared credential stays viewable. Default 365. |
DB_URI |
for mongodb, unless DB_HOST is set |
A mongodb:// or mongodb+srv:// connection string. |
DB_HOST, DB_USER, DB_PASS |
for mongodb, unless DB_URI is set |
The 2.x way to connect to MongoDB Atlas: the app builds mongodb+srv://DB_USER:DB_PASS@DB_HOST. |
DB_NAME, DB_COLLECTION |
no | Default verifier-plus and credentials. |
CREDENTIAL_TABLE |
for dynamodb |
The DynamoDB table. |
AWS_REGION |
for dynamodb |
The table's region. AWS Lambda sets it. |
DYNAMODB_ENDPOINT |
no | Only for DynamoDB Local, such as http://localhost:8000. |
A missing or invalid setting does not stop the server. Routes that need it answer 503 naming it, and GET /health/ready answers 503 with a list of every problem, so check it after a deployment:
$ curl http://localhost:3000/health/ready
{"status":"UP","problems":[],"components":{"credentialStore":{"status":"UP","durationMs":2}}}
3.0.0 requires two settings that 2.x did not have. If you set only DB_USER, DB_PASS and DB_HOST, add:
CREDENTIAL_STORE=mongodb
EXCHANGES=on
EXCHANGES=on keeps the "request credentials from the Learner Credential Wallet" option; use off to drop it. If you set NEXT_PUBLIC_EXCHANGE_SERVER_URL, rename it to EXCHANGE_SERVER_URL. Shared credentials now expire after a year; ones 2.x stored count from when they were shared. See the CHANGELOG for the rest.
Clone the repo then:
$ npm i
$ npm run dev
This spins up a dev server hosted at http://localhost:3000, which you can now open in a web browser.
npm run dev needs no database: .env.development sets CREDENTIAL_STORE=memory and EXCHANGES=on, so sharing works until the server stops. To use MongoDB or DynamoDB locally, set the settings for it in .env.local, which overrides .env.development.
Warning
Make sure you run the right npm script. There are two sets of scripts, one in the package.json in the root directory and another in the .next/standalone/package.json directory. The latter is for running on the server, and if you run it locally it doesn't work properly. It is particularly easy to accidentally run the standalone script if you are working in Visual Code because the standalone scripts appear above the regular scripts in the VCode NPM Scripts tab. Make sure you run these:
The development server updates as you save changes to the underlying files.
Set CREDENTIAL_STORE=mongodb and either DB_URI (any MongoDB, such as mongodb://localhost:27017) or, as in 2.x, DB_HOST, DB_USER and DB_PASS for a MongoDB Atlas cluster. To set up Atlas:
- create a Mongo Atlas cluster.
- from there create a collection, as well as a user with read and write permissions.
- copy
.env.exampleto.env - copy the connection details for your Atlas cluster into the appropriate fields in the
.envfile.
On first use the app creates two indexes on the collection: a unique index on id, and a TTL index on expiresAt that has MongoDB delete each record when it expires. If the collection already has a different index named id_1, sharing fails and /health/ready names the index to remove. Records that 2.x stored have no expiresAt; the app treats them as expiring CREDENTIAL_TTL_DAYS after their createdAt, and MongoDB does not delete them.
Tip
If the app can't connect to your Mongo Atlas collection, make sure that you've added your server IP to the whitelist for your Mongo Atlas account.
We've provided both a sample Dockerfile and two sample docker compose files.
The two docker compose files are identical except that the production version includes configuration for nginxproxy/nginx-proxy and nginxproxy/acme-companion to make it easier to run on your domain.
Both compose files include a HEALTHCHECK configuration that monitors the running web app container. If the healthcheck returns 'unhealthy' three times in a row, the the willfarrell/autoheal service restarts the container.
You can also configure an SMTP email server, which the healtcheck will use to send emails to an email recipient whose address you can also configure. The healthcheck only sends emails if the check returns unhealthy.
And finally you can set a webhook on both the healtcheck and the autoheal, to which the same notifications of unhealthy status will be sent. We use the Slack webhook for this.
We've set the configuation values in the 'environment' sections of the compose file, but you can also use a .env file, like the .env.example we provide. The .env file may be more secure.
Both compose files set CREDENTIAL_STORE=mongodb and EXCHANGES=on, which 3.0.0 requires (see Upgrading from 2.x). To run the image by hand:
$ docker build -t verifier-plus .
$ docker run -p 3000:3000 -e CREDENTIAL_STORE=mongodb -e DB_URI=mongodb://your-mongo-host:27017 -e EXCHANGES=on verifier-plus
Tip
If, when deploying to a different architecture, you get errors that seem related to tailwind, it may be that you need to include specific builds of the lightningcss library, which tailwind uses under the hood. The error should tell you which specific build is needed. You can then find the right package in npm and install it as an optionalDependency as we've already done for the linux build we needed for our AWS deployment: npm i lightningcss-linux-x64-musl --save-optional. You'll see in the optionalDependencies section of package.json that we've also installed another build for an M4 Mac, lightningcss-linux-arm64-musl.
VerifierPlus provides an option on the landing page to request credentials from the Learner Credential Wallet.
Turn it on or off with the EXCHANGES environment variable, which must be set to on or off. The landing page shows the option only when it is on, and /api/exchanges/... answers 404 "Exchanges disabled" when it is off. Exchanges are kept in the server's memory, so they need a single long-running server process: on AWS Lambda, EXCHANGES=on is refused, /health/ready reports it, and exchanges stay off.
Wallets reach the exchange at the address the browser used to reach the page. To give another address, set EXCHANGE_SERVER_URL to an absolute URL, such as https://verifierplus.org.
NEXT_PUBLIC_EXCHANGE_SERVER_URL is no longer read; set EXCHANGE_SERVER_URL instead.
See .env.example for an example
The exchange is temporary: transaction-service is its planned home. The code to remove then is marked TEMPORARY(transaction-service).
npm run build:lambda builds the app for AWS Lambda into dist/lambda/: the Next.js standalone server, its static files, and run.sh, which the Lambda Web Adapter starts. Build on Linux x86_64 for a deployable artifact, because the build includes native modules for the platform it ran on.
On Lambda, use CREDENTIAL_STORE=dynamodb with CREDENTIAL_TABLE, and EXCHANGES=off. The table's key is the string attribute id, and its TTL attribute is expiresAt. The Digital Credentials Consortium's deployment lives in its platform repository, not here.
To try the build locally:
$ npm run build:lambda
$ CREDENTIAL_STORE=memory EXCHANGES=off PORT=3000 dist/lambda/run.sh
npm test runs the unit tests with Vitest. They need no database and no network: each store's tests run against the memory store.
npm run test:stores runs the same store tests against MongoDB and DynamoDB Local as well. Start both first with docker-compose.test.yml:
$ docker compose -f docker-compose.test.yml up -d
$ npm run test:stores
TEST_STORES picks the stores (a comma list of memory, mongodb, dynamodb); TEST_MONGO_URI and DYNAMODB_ENDPOINT point at other servers. A store that is named but unreachable fails the run rather than being skipped.
We use Playwright for end-to-end testing, pretty much as described on the excellent Playwright site, so we won't reproduce the Playwright documentation.
The basic idea, though, is that the playwright tests check a running server, which by default
is localhost, but can be set to any server by setting PLAYWRIGHT_TEST_URL in .env.playwright, like so:
PLAYWRIGHT_TEST_URL=https://verifierplus.org
This therefore allows us to run end to end tests on our local development server, on a staging server, or on a production server. Any running instance of verifier-plus.
You can also pass the value in on the command line if you like, e.g.,
PLAYWRIGHT_TEST_URL=http://localhost:3000 npm run test:e2e
npm run test:e2e runs three projects: API (the credential API), DesktopChrome (the pages), and Lambda (what a deployment on AWS Lambda must get right: readiness, reads straight after writes, and the size limits). The test that requests credentials from the wallet asks /api/config first and is skipped when exchanges are off. Some tests fetch credentials and registries from the internet.
Note too that you can set which browsers you'd like to run the tests on using the --project flag as described in this Playwright doc. Note that you'll have to have defined the projects in the playwright.config.ts.
.github/workflows/ci.yml runs on every pull request: the unit tests and types, the store tests against MongoDB and DynamoDB Local, the Lambda build with the end-to-end tests against dist/lambda/run.sh, and the Docker image with MongoDB and the end-to-end tests.
Tip
If for whatever reason you don't want to set the playwright PLAYWRIGHT_TEST_URL as an environment variable you can of course also directly change the baseURL in playwright.config.ts.
To learn more about Next.js, take a look at the following resources:
- Next.js Documentation - learn about Next.js features and API.
- Learn Next.js - an interactive Next.js tutorial.

