> 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/how-it-works.md). # How It Works Every credential in Blerify involves three parties: an **issuer** who creates it (a government, a university, an employer), a **holder** who carries it in the wallet on their phone, and a **verifier** who checks it. What makes the model powerful is what's missing — no central database anyone has to call or trust. The credential itself carries the proof. This design follows the W3C Verifiable Credentials standard. This page explains how that works end to end: how a credential gets issued, how it's checked, and how much you can rely on each verification. *** ## The three participants | Participant | What they do | Blerify product | | ------------ | -------------------------------------------------------------------------------- | --------------- | | **Issuer** | Creates and cryptographically signs a credential, then delivers it to the holder | Issuance | | **Holder** | Stores the credential on their device, decides what to share and with whom | ID Wallet | | **Verifier** | Asks the holder to present a credential and checks its validity | Verification | These three roles never need to communicate directly with each other. The trust between them is established by the credential's cryptographic signature and by the Blerify Trust Registry, which records which issuers are authorized to issue which credential types. *** ## End-to-end flow ### 1 — Issuance The issuer creates a credential containing the holder's data — name, document number, qualification, or whatever the use case requires — signs it with their private key, and delivers it to the holder's wallet. ``` Issuer backend ──▶ Blerify Issuance API ──▶ Signed credential │ ▼ Holder's Wallet ``` The credential is signed once at issuance and never modified afterward. If the issuer later revokes it, they update the revocation registry. The credential in the wallet remains unchanged, but any subsequent verification will reflect the revoked status. ### 2 — Holding The holder receives the credential into the Blerify Wallet via a QR code, a deep link, or a push notification. The wallet stores the credential on-device, encrypted at rest, and unlockable only with the holder's biometric or PIN. The holder controls consent: when a verifier requests a credential, the wallet shows them exactly which fields will be shared before anything leaves the device. ### 3 — Presentation The holder presents the credential to the verifier. This can happen in three ways: **Same-device** — the holder is on a mobile web page or inside a native app. A button or deep link opens the Blerify Wallet on the same phone. They approve with their biometric, and the app or page receives the result. **Cross-device** — the holder is at a desktop. They scan a QR code with their phone. The wallet opens, they approve, and the desktop page updates. **App-to-app** — the holder is inside a native mobile app. A deep link opens the wallet directly. The wallet finishes and returns focus to the calling app. In all three cases, the holder's explicit approval is required before any data leaves their device. ### 4 — Verification The verifier's backend creates a verification session with Blerify and gets back a `transaction_id`. The verifier's frontend uses that to build a QR code or deep link for the holder. The wallet submits a signed presentation directly to Blerify. The verifier's backend polls for the result. ```mermaid sequenceDiagram participant VB as Verifier Backend participant Blerify participant VF as Verifier Frontend participant W as Holder's Wallet VB->>Blerify: Create verification session Blerify-->>VB: transaction_id Note over VB,VF: Backend hands transaction_id to frontend VF->>W: Show QR code / deep link W->>Blerify: Submit signed presentation VB->>Blerify: Poll for result Blerify-->>VB: Verified data ``` The verifier's backend is the only party that calls the Blerify API. The service account token that authenticates those calls must never be exposed to a browser or mobile app. *** ## What Blerify validates When a credential is presented, Blerify runs all of these checks automatically: | Check | What it verifies | | --------------------- | --------------------------------------------------------------------------------- | | **Signature** | The credential was signed by a key belonging to a registered issuer | | **Trust chain** | The issuer is in the Trust Registry and authorized to issue this credential type | | **Revocation** | The issuer has not revoked this credential | | **Expiry** | The credential is within its validity period | | **Holder binding** | The presentation was made by the person who controls the credential's private key | | **Replay protection** | The presentation includes a fresh nonce — it cannot be reused | You don't implement any of these checks. You receive a structured result on each one and apply your own access policy on top. *** ## The Trust Registry The Trust Registry is the source of truth for who can issue what. When Blerify validates a credential, it checks the registry to confirm: * The issuer exists and is active * The issuer is authorized to issue the specific credential type being presented * The issuer's signing key matches what's recorded in the registry The Trust Registry uses Blerify's DID method (did:lac1) to anchor issuer identities on a public ledger. This means the trust chain is verifiable by anyone — including verifiers outside the Blerify ecosystem. See [Decentralized Root of Trust](/trust-registry/decentralized-root-of-trust.md) for the full technical model. *** ## Credential formats **W3C Verifiable Credentials** are JSON documents signed as JWTs. The schema is flexible — issuers define their own claim types. Commonly used for soft credentials: licenses, badges, KYC status, employment records. **ISO 18013 mDocs** are binary CBOR documents following the ISO 18013-5 standard for mobile driving licenses. The schema is defined by the ISO standard and uses standardized field names and namespaces. Used for government identity documents. Both formats travel the same way, over OpenID4VP — the open protocol wallets use to present credentials to verifiers. The validation pipeline detects the format and routes to the appropriate verification path automatically. *** ## Assurance tiers Not all verifications carry the same weight. Blerify reports an `assurance_level` — `BASIC`, `STANDARD`, or `PREMIUM` — alongside every verification result. The tier reflects what can be independently proven to you, not just what the wallet asserts. | Tier | What it proves | | ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Basic** | The credential is cryptographically valid, the issuer is trusted, the credential isn't revoked, and the holder presented it in real time. Works with any wallet that follows the open presentation standard. | | **Standard** | Everything in Basic, plus the signing key is proven to reside in tamper-resistant hardware (TEE or Secure Enclave). The verifier receives a hardware attestation certificate chain they can validate independently against Google or Apple roots. | | **Premium** (coming soon) | Everything in Standard, plus the person physically holding the device is confirmed to be the credential subject. Blerify captures a live selfie from within the wallet, compares it against the photo embedded in the signed credential, and returns the result. | The tier you receive depends on the wallet submitting the proof. Any wallet that follows the open standard achieves Basic. Standard and Premium require the Blerify Wallet, which submits hardware attestation evidence alongside the credential presentation. You choose the tier when you configure the verification. If the wallet can't supply the evidence that tier requires, the verification fails with an explicit reason rather than quietly completing at a lower level. See [Assurance Tiers](/introduction-to-verification/learn/assurance-tiers.md) for the full model, including the informative mapping to eIDAS and NIST frameworks. *** ## Privacy model **Selective disclosure.** When a verifier requests a credential, they specify which fields they need. The wallet shows a consent screen listing exactly those fields. The holder approves or declines. Blerify only forwards what the holder approved. **No call home.** The issuer is not notified when a holder presents a credential. Blerify does not maintain a presentation log accessible to issuers. The issuer's involvement ends at issuance. **On-device storage.** Credentials are stored in the Blerify Wallet on the holder's device, not in a Blerify cloud database. If the holder uninstalls the wallet, the credentials are gone from Blerify's systems. **No biometric storage.** When Premium assurance is requested, Blerify compares a live selfie against the photo embedded in the credential, then immediately deletes both. Blerify stores only the boolean result and a confidence score. There is no face database, no biometric template, and nothing to breach beyond a pass/fail flag. *** ## Next steps * Issue your first W3C credential — [Issuance: Get Started](/introduction-to-issuance/build/get-started.md) * Verify your first credential — [Verification: Get Started](/introduction-to-verification/build/get-started.md) * Understand how trust anchors work — [Decentralized Root of Trust](/trust-registry/decentralized-root-of-trust.md) * Learn how assurance tiers map to eIDAS and NIST — [Assurance Tiers](/introduction-to-verification/learn/assurance-tiers.md) --- # 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/how-it-works.md?ask=&goal= ``` `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.