Get Started with a Verification
This page walks you through your first working verification — from authenticating your service account to reading the result. By the end, you'll have made a real API call and seen a credential verified.
Prerequisites
A Blerify service account with the
verifications.apirole — see AuthenticationA verification template created in the Blerify Portal. A template is a one-time configuration that defines which credential to request, which issuer to trust, and what assurance level to require. The Portal gives you a template UUID; the examples below use
{your-template-uuid}as a placeholder
How it works
A verification has four steps:
Your backend starts a session by calling the Blerify API with your template UUID
Blerify returns the data your frontend needs to invoke the wallet — as a button, a link, or a QR code
The user opens their wallet, reviews what you're requesting, and approves with their biometric
Your backend retrieves the result
Blerify handles everything between steps 2 and 4: the credential protocol, the cryptographic validation, the trust chain check, and the revocation lookup. You never see the raw credential in transit — you receive a structured result with the fields your template requested and a per-credential verdict.
Your backend talks to Blerify. The wallet connects to Blerify directly on behalf of the user. You never implement credential parsing, signature verification, or trust chain logic.
Step 1 — Authenticate your service account
Your backend authenticates with Blerify using the OAuth 2.0 client_credentials grant with private_key_jwt as the client authentication method (RFC 7523). See Authentication for how to create a service account and construct the signed JWT. Once you have one:
Use this token in the Authorization header for all subsequent requests. Cache it and refresh before expiry rather than requesting a new one on every call.
Step 2 — Start a verification session
Your backend calls Blerify with your template UUID to create a session. Every session requires a fresh, random nonce your backend generates — it binds the presentation to this session and prevents replay:
Keep transaction_id — it's your polling key for this session. The other four fields (request_id, request_uri_method, client_id_scheme, client_id) are what you use to build the wallet link in the next step — copy them verbatim, don't rename or transform them.
client_context.session_ip is optional but recommended. Blerify compares the IP you report here with the IP it observes from the user's wallet, and includes the comparison in the evidence package at Standard tier and above. redirect_uri is optional too, but required if you want the user's browser to return to your app after a same-device flow — it must match a URI you whitelisted in the Portal.
Step 3 — Build the wallet link and show the user a prompt
The wallet is invoked through a single Universal Link — the same one works whether you render it as a button, a QR code, or open it from a native app:
Copy client_id, client_id_scheme, and request_uri_method verbatim from the Step 2 response. The request_uri parameter is different — it's a URL you construct yourself from request_id, pointing at the wallet-facing endpoint for this specific session, then URL-encoded:
All four query parameters are required — drop or rename any one of them and the wallet won't open the right flow.
Same-device (user is on their phone): render a button or anchor with the link. The OS routes it to the Blerify Wallet app directly.
Cross-device (user is on a desktop): encode the same Universal Link as a QR code using any standard library. The user scans it from their wallet app on their phone.
App-to-app (user is inside your native mobile app): save transaction_id to local storage before launching, then open the link via the platform's URL-opening API. When the wallet finishes, the OS returns focus to your app and you poll for the result. See Mobile Integration for the platform-specific code.
Step 4 — Wait while the user completes the flow
The user opens their wallet, sees a consent screen showing exactly what you're requesting, and approves with their biometric. The wallet submits the signed presentation to Blerify directly. Your code is not involved in this step.
Step 5 — Poll for the result
Poll every 1–2 seconds until you get a terminal status:
While the user is still in the flow:
You may also see CREATED, SUBMITTED, or VALIDATING during the session — treat all of these the same way and keep polling. Stop when status is COMPLETED or FAILED.
When the user finishes:
Reading the result
Each entry in credentials[] has two parts:
result— per-credential facts.credential_validis the overall verdict, backed by the individual checks that feed it:signature_valid,issuer_trusted,revoked,expired, andholder_bindingdata— the verified fields from the credential, organized by namespace
status reports whether verification ran — not whether the credential is acceptable. A revoked or expired credential returns COMPLETED with the relevant flags set inside credentials[].result. You apply your own policy. FAILED is reserved for process errors where Blerify could not produce a trustworthy verdict at all.
Two fields tell you about assurance level:
assurance_level— what your template requestedeffective_tier— what the evidence actually supports
They usually match. They differ when the wallet can't deliver the attestation data your template requires — for example, a third-party wallet without Blerify extension support completes at effective_tier: BASIC even when you configured STANDARD. Always check effective_tier when enforcing your risk policy.
Choose your integration pattern
The steps above apply to every integration. What varies is how your frontend triggers the wallet and handles the user returning to your app.
If you're not sure which pattern fits, Verify from a Web App is the most direct path to a working integration.
Next steps
Continue to Verify from a Web App — the complete guide for building your own verification UI, including all three presentation scenarios, error cases, and the full result schema.
See also: Assurance Tiers · Authentication · API Reference
Last updated