Verifiable credentials can support privacy-aware identity verification, but a successful implementation depends on more than issuing a signed digital document. This guide provides a reusable checklist for designing the full workflow: issuer, wallet, holder, verifier, trust registry, revocation, recovery, and operational testing.
Overview
A verifiable credential is a digitally signed statement about a subject, such as a qualification, organization membership, age range, or account attribute. The subject may hold the credential in a digital wallet and present it to a verifier when a service needs evidence. Unlike a conventional database lookup, the verifier may be able to validate the credential without contacting the original issuer for every transaction.
That model creates three separate questions that teams should not combine:
- Is the credential authentic? The verifier checks its proof, signature, issuer information, and required claims.
- Is the credential currently acceptable? The verifier evaluates expiration, status, intended use, policy, and any presentation requirements.
- Should this issuer be trusted? The verifier checks whether the issuer belongs to an accepted trust framework, registry, or partner list.
A useful role-based architecture looks like this:
Issuer system
| issues credential after an approved process
v
Holder wallet ---- presents proof or credential ----> Verifier service
| |
| stores and manages credentials | validates proof and policy
v v
Recovery and status services Trust registry or issuer directoryThe roles may be operated by different organizations or combined within one product. Document the separation even when the same team owns multiple components. It clarifies which system is responsible for identity proofing, key protection, consent, status information, logging, and support.
Before selecting a wallet or protocol, define the business decision the verifier must make. “Verify a person” is too broad. A better requirement might be “confirm that the presenter holds a credential issued by an approved training organization, that it has not expired or been revoked, and that only the qualification level is disclosed.” The narrower requirement determines the claims, proof format, trust policy, retention period, and user experience.
Checklist by scenario
1. Planning the credential model
- Write the exact decision the credential will support and identify who makes it.
- Define the subject of the credential: a person, organization, device, account, or another entity.
- List required claims and separate them from optional claims.
- Use the least revealing claim that satisfies the decision. For example, an eligibility category may be preferable to a full date of birth when the exact date is unnecessary.
- Define credential validity, intended audience, allowed uses, and presentation constraints.
- Decide whether the credential is designed for direct presentation, selective disclosure, or a request-and-response flow.
- Record data retention and deletion requirements before implementation, not after launch.
2. Building the issuer
- Document how the issuer establishes the subject’s identity or eligibility before issuing a credential.
- Separate identity-proofing evidence from the final credential where possible; do not copy every verification artifact into the credential.
- Protect issuer signing keys with an approved key-management process and define access controls for issuance operations.
- Publish the issuer’s verification material in a way that verifiers can retrieve and validate reliably.
- Define an issuance status: requested, approved, issued, suspended, revoked, or expired.
- Make issuance idempotent where practical so retries do not create confusing duplicate records.
- Provide a support process for correcting inaccurate claims without silently modifying an already-issued credential.
3. Choosing or designing the wallet
- Identify whether the wallet is controlled by the user, an organization, a device, or a managed service.
- Explain clearly what the wallet stores, what leaves the device, and which actions require user approval.
- Protect credentials at rest and require suitable device or application authentication.
- Plan for backup, device replacement, account recovery, and loss of access. Recovery should not become an unreviewed method of issuing credentials to an impostor.
- Show the verifier, requested claims, purpose, and destination before presentation.
- Support deletion and credential lifecycle controls that match the product’s privacy commitments.
4. Implementing the verifier
- Validate the cryptographic proof rather than trusting claims because they appear in a familiar format.
- Check issuer identity, subject binding, audience or recipient, issuance time, expiration, status, and required proof-of-possession conditions.
- Reject algorithms, proof types, or credential formats that the service has not explicitly approved.
- Apply a trust policy after technical validation. A valid signature alone does not prove that the issuer is acceptable for the transaction.
- Minimize stored presentation data. Record the decision and necessary audit evidence instead of retaining a complete credential by default.
- Return actionable failure messages to the user while avoiding details that help an attacker probe verification rules.
5. Operating trust registries
- Define who can add, remove, suspend, or update an issuer entry.
- Record the issuer identifier, approved credential types, applicable purpose, effective dates, and responsible governance authority.
- Distinguish an issuer directory from a trust decision. Listing an organization does not automatically mean every credential it issues is acceptable.
- Design for registry availability, caching, rollback, and emergency changes.
- Audit changes to issuer keys, endpoints, credential schemas, and trust status.
- Document how a verifier behaves when the registry is unavailable: fail closed, use a bounded cache, or route the case for review.
6. Managing status, revocation, and recovery
- Choose status behavior for each credential type. Some credentials may need rapid invalidation; others may only need expiration.
- Explain whether status checks reveal information about the holder or their transactions.
- Test a revoked, suspended, expired, and not-yet-valid credential separately.
- Define who can request revocation and how requests are authenticated and reviewed.
- Rotate issuer keys through a documented process and test verification during overlap and after retirement.
- Plan wallet recovery and reissuance, including how old credentials are invalidated and how duplicate identities are handled.
Standards and interoperability decisions
Standards should be treated as implementation constraints and interoperability contracts, not as a substitute for a trust model. A team may encounter several related layers:
| Layer | What it addresses | Questions to ask |
|---|---|---|
| Credential data model | How claims, issuer, subject, dates, and proofs are represented | Can our issuer and verifier agree on schemas, proof handling, and required fields? |
| Decentralized identifiers or issuer identifiers | How entities are identified and how verification material is discovered | How are identifiers resolved, updated, and governed? |
| Issuance protocol | How a wallet requests and receives a credential | How are authorization, consent, retries, and error states handled? |
| Presentation protocol | How a verifier requests evidence and how a wallet responds | Can the flow support audience binding, selective disclosure, and user review? |
| Status mechanism | How expiration, suspension, or revocation is communicated | What happens when status data is delayed, unavailable, or privacy-sensitive? |
| Trust framework | How the verifier decides which issuers and credential types to accept | Who governs membership, policy changes, and dispute handling? |
When evaluating a vendor or open-source component, ask for an interoperability matrix rather than a general standards statement. It should identify supported credential formats, issuance and presentation flows, proof types, wallet environments, status methods, key-management options, and known limitations. Confirm which capabilities are production-ready, which are experimental, and which require custom integration.
What to double-check before launch
Selective disclosure and data minimization
Test whether the presentation reveals only the claims requested by the verifier. Check derived or predicate-based proofs as well as ordinary claim filtering. Also review metadata: timestamps, unique identifiers, issuer URLs, and transaction logs can create linkability even when the visible claim set is small.
Audience binding and replay resistance
A presentation intended for one verifier should not be reusable at another service without an explicit policy decision. Use a challenge, nonce, audience, or equivalent mechanism appropriate to the selected protocol. Test duplicate submissions, delayed submissions, and a presentation copied from one account to another.
Key rotation and discovery
Verify that the verifier can retrieve the correct issuer key, distinguish current and retired keys, and reject an unknown or unauthorized key. Test rotation during an active issuance period and confirm that old credentials remain verifiable only for the period your policy permits.
Expiration, status, and clock handling
Test boundary conditions around issuance, expiration, suspension, and revocation. Define acceptable clock skew and behavior when a status endpoint is unavailable. Do not let a temporary network failure silently convert into unconditional acceptance.
Recovery and account linking
Review every route by which a user can move a wallet to a new device, link a credential to an account, or request reissuance. Recovery should preserve user access without weakening issuer assurance. Log security-sensitive changes and notify the user through an established channel where appropriate.
Test-case template
For each test, record: scenario, starting state, input credential or presentation, expected decision, expected user message, audit event, privacy impact, and cleanup action. Include at least these cases:
- Valid credential with the minimum required disclosure.
- Credential with an invalid signature or altered claim.
- Expired, suspended, and revoked credentials.
- Credential from an untrusted issuer with otherwise valid cryptography.
- Wrong audience, missing challenge, replayed presentation, and duplicate submission.
- Rotated issuer key and unavailable key-discovery service.
- Wallet loss, recovery, reissuance, and attempted use of the old credential.
- Selective-disclosure failure that accidentally exposes an unnecessary claim.
Common mistakes
- Confusing authenticity with trust. A mathematically valid signature does not establish that the issuer is approved for the business decision.
- Designing the credential before the policy. Start with the decision, evidence, retention rule, and dispute path; then choose claims and formats.
- Putting sensitive source evidence into the credential. A credential should normally carry the result needed for verification, not an entire identity-proofing file.
- Ignoring operational failure. Key endpoints, registries, status services, and wallets can be unavailable. Define safe, observable behavior for each dependency.
- Treating recovery as a convenience feature. Weak recovery can undermine strong issuance and presentation controls.
- Assuming interoperability from shared terminology. Test actual issuer-wallet-verifier combinations, schemas, proof types, and error handling.
- Keeping every presentation forever. Retain only what supports security, compliance, dispute resolution, and legitimate operations.
When to revisit
Review the implementation before each pilot or production launch, after changing credential schemas, wallets, issuers, verifiers, key-management systems, or trust-registry rules. Revisit it during seasonal planning cycles, partner onboarding, annual trust-model reviews, and incident postmortems. A standards or protocol release is also a reason to compare supported versions and reassess interoperability rather than upgrading automatically.
Use this short review sequence:
- Confirm the business decision and whether the current claims remain necessary.
- Check issuer approval, registry governance, key rotation, status, and recovery procedures.
- Run the negative test suite, including failed signatures, wrong audiences, expired credentials, unavailable dependencies, and privacy leaks.
- Review wallet prompts, consent language, retention, logs, and user support paths.
- Record changes, owners, test evidence, and the next review date.
For related identity controls, pair this review with an identity verification vendor evaluation, an identity verification workflow review, and a signing-key rotation runbook. The goal is not simply to issue a credential. It is to maintain a verifiable, privacy-aware, and governable trust decision from issuance through recovery and eventual retirement.