Implementing verifiable credentials on the web requires more than adding an issuance endpoint. You need a clear trust model, wallet journey, credential schema, verification policy, privacy controls, and operational plan. This guide provides a reusable implementation checklist, a practical web architecture, sample request sequences, and a neutral comparison framework for vendors, DID methods, and SDKs.
Overview
Verifiable credentials are digitally signed claims that can be issued to a person or organization and later presented to another party. A typical flow has three roles:
- Issuer: the organization that creates and signs a credential.
- Holder: the person or organization that stores the credential in a wallet or compatible application.
- Verifier: the web application that requests and checks a presentation.
A credential may state that a user completed training, holds a membership, meets an age requirement, or passed an identity verification process. The credential is not automatically trustworthy simply because it is digitally signed. Your verifier must still check who issued it, whether it is within its validity period, whether it has been revoked or suspended where applicable, and whether the presented subject is the account holder or session participant.
For a web application, keep the first implementation narrow. Define one use case, one credential type, and one verification decision. For example: “Allow access to a partner portal when a presentation contains a valid organization-issued employee credential.” Avoid beginning with a general-purpose identity platform before the business rule is understood.
Reference architecture
Issuer service ──signs──> Credential
│ │
│ delivery / invitation │ stored by
▼ ▼
User onboarding ───────────> Identity wallet
│
presents credential
▼
Web app ──> Verification API ──> Trust and policy checks
│
▼
Allow, deny, or review
Separate cryptographic verification from business authorization. The verification component can establish that a presentation is valid under your configured rules; the application must then decide what that result permits. Store the minimum result needed for the decision rather than retaining the entire presentation by default.
Checklist by scenario
Before choosing a vendor or SDK
- Write the credential use case in one sentence and identify the issuer, holder, and verifier.
- List the claims you actually need. Do not request a full identity profile when an age range, role, or membership status is sufficient.
- Decide whether users will bring an existing wallet, use a vendor-provided wallet, or access a wallet through an embedded experience.
- Record required environments: browser, mobile browser, native mobile application, backend-only, or a combination.
- Ask how the product handles key management, credential storage, recovery, account deletion, and lost-device scenarios.
- Confirm which credential formats, presentation formats, DID methods, signing algorithms, and status mechanisms are supported by the exact SDK version you plan to deploy.
- Request documentation for webhook authentication, idempotency, retries, timeouts, rate limits, and error codes.
- Define an exit plan: exportable data, replacement credentials, migration support, and how your application will operate if the provider is unavailable.
When issuing credentials
- Authenticate the subject. Establish why the issuer is entitled to make the claim. This may involve an existing account, document verification, organizational approval, or another controlled process.
- Construct the claims. Use stable identifiers where necessary, but avoid putting unnecessary personal data into an immutable or widely shared credential.
- Apply a schema version. Give the credential type and version a clear identifier so verifiers can distinguish future changes from the original contract.
- Sign through a protected key. Keep issuer keys out of browser code and ordinary application logs. Define rotation and compromise procedures before production use.
- Deliver through a recoverable flow. Show the user what is being issued, who issued it, and where it will be stored. Design for interruption, expired invitations, duplicate clicks, and switching devices.
- Record operational evidence. Maintain an issuance reference, schema version, key identifier, and outcome without creating a duplicate store of sensitive claims unless required.
For data mapping, webhook design, and failure handling, use the Credential Verification API Integration Checklist alongside your implementation ticket.
When verifying credentials
- Create a verifier policy containing accepted credential types, trusted issuers, permitted subjects, required claims, acceptable time windows, and status rules.
- Generate a presentation request on the server, not solely in client-side code.
- Bind the request to the current session with a nonce, expiration time, and transaction or state identifier.
- Ask for the smallest presentation that satisfies the policy.
- Validate the presentation cryptographically and semantically. A valid signature alone is not enough.
- Check replay resistance, audience or domain binding where supported, issuer trust, schema version, expiration, and status.
- Return a narrow result to the application, such as
verified,not_verified, ormanual_review, with a machine-readable reason.
Sample web request sequence
POST /api/presentation-requests
Authorization: Bearer <server-token>
Content-Type: application/json
{
"sessionId": "session_123",
"purpose": "partner_portal_access",
"acceptedCredentialTypes": ["OrganizationMembership"],
"requestedClaims": ["organizationId", "membershipStatus"],
"expiresInSeconds": 300
}
// Response
{
"requestId": "req_456",
"requestUri": "https://wallet.example/request/req_456",
"expiresAt": "2026-11-05T12:05:00Z"
}
The browser can display a QR code, deep link, or wallet handoff using the provider's supported method. The backend should wait for a verified callback or poll a documented status endpoint. Never treat “wallet opened,” “QR code scanned,” or “callback received” as proof of a valid credential.
Comparison framework
Feature matrices become unreliable when they mix product tiers, SDK versions, and optional integrations. Use this baseline table during procurement, then verify each item against current technical documentation and a proof of concept.
| Approach | Useful when | Questions to ask | Tradeoffs to examine |
|---|---|---|---|
| Managed verification API | You need a fast pilot or a small engineering team. | Which credential formats, wallets, issuer registries, status checks, and export options are supported? | Less infrastructure work, but potentially more provider dependency and less control over data flow. |
| Managed issuance and wallet platform | You need onboarding, issuance, wallet delivery, and support in one workflow. | Can users recover credentials? Can you change wallet providers without re-enrolling everyone? | Simpler user experience may come with tighter coupling to the platform's wallet model. |
| Open-source SDK and self-hosted services | You require control over keys, deployment, and integration behavior. | Who maintains dependencies, security patches, documentation, and compatibility testing? | More control, but your team owns operations, upgrades, monitoring, and incident response. |
| Direct DID-method integration | Your trust model requires a particular identifier or registry approach. | How are keys rotated, identifiers resolved, and status information published? | Can provide a deliberate trust model, but may increase interoperability and migration work. |
Compare DID methods by operational behavior rather than branding: resolution reliability, key rotation, recovery, privacy characteristics, governance, cost model, ecosystem support, and what happens during an outage. Treat a DID as an identifier mechanism, not as automatic evidence of a person's real-world identity.
What to double-check
- Trust configuration: Document exactly how trusted issuers are added, removed, reviewed, and audited. A verifier that accepts every issuer defeats the purpose of a trust policy.
- Session binding: Ensure a presentation from one browser session cannot be attached to another account or transaction. Use short-lived, single-use state.
- Privacy: Check whether logs, analytics, support tools, and vendor dashboards capture credential claims, wallet identifiers, or presentation payloads. Mask or omit them where possible.
- Key protection: Restrict signing operations, separate development and production keys, monitor unusual activity, and rehearse key replacement.
- Accessibility: Test QR, deep-link, camera, screen-reader, keyboard, and assistive-technology paths. A credential flow is not complete if users cannot reliably reach the verification step. See the accessible identity verification testing checklist.
- Failure handling: Give users a useful next step for expired requests, unsupported wallets, revoked credentials, clock differences, and temporary provider errors. Keep security reasons specific in internal logs but suitably limited in public messages.
- Identity assurance: Do not assume that a credential's presence proves the assurance level your use case needs. If the credential depends on document, biometric, or liveness checks, review how those upstream controls were performed and what evidence is available.
For workflows that include face match or liveness checks, the liveness detection testing checklist can help separate the credential layer from the identity-proofing layer.
Common mistakes
- Starting with a wallet instead of a decision: Select the credential and policy needed for the business action first.
- Putting secrets in frontend code: Issuer signing keys, provider credentials, and trusted-issuer administration belong on controlled backend systems.
- Accepting a successful HTTP response as verification: Inspect the provider's structured verification result and apply your own policy.
- Logging complete presentations: Full payloads make debugging easier but can create unnecessary privacy and retention risk. Log references, outcomes, and reason codes instead.
- Ignoring replay and race conditions: A request should be bound to one user session and consumed once. Test duplicate callbacks and simultaneous browser tabs.
- Hard-coding schema assumptions: Version schemas and reject or route unknown versions rather than silently interpreting new fields.
- Confusing decentralized identity with anonymity: Verifiable credentials can reduce repeated disclosure, but identifiers, metadata, and issuer records may still be linkable.
- Skipping manual review design: Define what happens when a credential is technically valid but conflicts with account information, policy, or risk signals.
If your team is integrating an existing identity verification process, compare the credential result with the underlying workflow described in the identity verification workflow guide, rather than treating the credential as a replacement for every control.
When to revisit
Review the implementation before major planning cycles and whenever the workflow or tooling changes. At minimum, schedule a quarterly technical and compliance review, then perform an immediate review after a critical security advisory, issuer-key event, wallet change, SDK upgrade, DID-method change, or significant standards update. The interval should be shorter for high-risk identity, access, financial, or age-related decisions.
Use this practical maintenance checklist:
- Re-run the issuance and verification test suite against the versions deployed in production.
- Confirm that trusted issuer lists, schemas, status endpoints, key identifiers, and expiration rules are current.
- Review provider release notes, security advisories, dependency changes, and breaking API changes.
- Test recovery, revocation or suspension handling, expired invitations, duplicate callbacks, and provider downtime.
- Sample logs and retention settings to confirm that sensitive claims are not being collected unnecessarily.
- Recheck accessibility and device coverage after changes to browser, wallet, QR, deep-link, or camera components.
- Update the vendor comparison matrix with the exact SDK versions, supported DID methods, formats, and deployment assumptions used by your team.
- Record the review decision, open risks, owner, and next review date.
Keep a short implementation record with the credential schema, trust policy, request and callback examples, test cases, incident contacts, and migration plan. That record will help new engineers onboard quickly and give reviewers a concrete basis for auditing the digital identity flow.