Verifiable credential status checking is the control that helps a verifier decide whether a credential should still be accepted. This guide provides a reusable implementation and operations checklist for checking expiry, revocation, suspension, issuer trust, status-list freshness, privacy, and service outages without collecting more identity data than the transaction requires.
Overview
A verifiable credential can be cryptographically well-formed and still no longer be acceptable. It may have expired, been revoked after a correction or fraud report, been temporarily suspended, or come from an issuer whose authority is no longer trusted in the relevant workflow. Status checking is therefore one part of digital credential validation, alongside proof verification, issuer validation, subject or holder binding, schema checks, and policy evaluation.
There is no single status mechanism that every credential ecosystem uses. A profile may use an issuer-hosted status endpoint, a privacy-preserving status list, a revocation registry, or a combination of expiry and issuer policy. The credential normally identifies how its status should be checked, but the verifier must also know which methods and issuers it trusts. Do not treat the presence of a status field as proof that the credential is valid.
A practical verifier separates four decisions:
- Is the presentation authentic? Verify the presentation proof, credential proof, signatures, timestamps, and any required holder binding.
- Is the credential within its validity period? Check issuance and expiration rules using a reliable time source and the profile’s permitted clock tolerance.
- Does the issuer report an acceptable status? Resolve and validate the referenced status mechanism rather than relying on a locally stored copy without freshness controls.
- Does the credential satisfy the business policy? A credential can be valid but still fail an age, role, jurisdiction, assurance, or transaction-specific requirement.
For a broader build plan, pair this article with the verifiable credentials implementation guide and the credential verification API integration checklist.
Checklist by scenario
Scenario 1: Building a verifier
- Identify the credential profile. Record the data model, proof type, status method, issuer identifier format, supported wallet behavior, and required trust anchors. Avoid assuming that a field or status URI has the same meaning across ecosystems.
- Parse the status reference safely. Validate its structure, permitted scheme, expected type, and relationship to the credential. Reject malformed, unexpected, or ambiguous references.
- Verify the credential before status lookup. Check the issuer proof, credential subject, presentation proof, holder binding where required, and any nonce or audience value used to prevent replay.
- Check time-based validity. Compare issuance and expiration values with a trusted clock. Define how the system handles missing dates, invalid date formats, future issuance times, and small clock differences.
- Retrieve the status object. Use authenticated transport where appropriate, validate the response, and enforce timeout, size, redirect, and content-type limits. A successful network response is not automatically a valid status response.
- Validate freshness and integrity. Check the status object’s signature or integrity protection, issuer association, version information, and freshness metadata when supplied. Document cache duration and whether stale data can ever support an approval.
- Interpret the result according to policy. Distinguish active, revoked, suspended, expired, unknown, unavailable, and malformed states. Do not collapse all non-active outcomes into a generic “invalid” error if operators need to diagnose the cause.
- Record a minimal decision trace. Store the policy version, decision time, status result, status source, and relevant error code. Avoid retaining the full credential or unnecessary personal data unless there is a documented purpose and control.
Scenario 2: Issuing credentials with revocation or suspension
- Define the events that require expiration, revocation, or temporary suspension. For example, document a correction process separately from a suspected compromise process.
- Assign clear authority for each action, including who may request, approve, reverse, and audit a status change.
- Choose whether the credential carries a status reference, whether status is resolved through a directory, and how the verifier obtains the current status information.
- Use identifiers that reduce unnecessary correlation between a person’s presentations. Where a status-list design supports privacy-preserving indexing, document the privacy assumptions and operational limits rather than treating privacy as automatic.
- Make updates atomic from the verifier’s perspective. Test what happens if a status record is written but its distribution mechanism is delayed.
- Publish operational rules for status recovery, key rotation, issuer migration, and accidental changes. Keep an audit trail for administrative actions without exposing it through public status responses.
Scenario 3: Handling a verifier outage or unavailable status service
Decide in advance whether an unavailable status service causes rejection, a pending decision, or limited acceptance. The answer depends on transaction risk, the credential’s purpose, the maximum permitted status age, and applicable internal policy. A low-risk presentation may tolerate a short-lived cached result; a high-risk action may require a fresh check.
- Set explicit connection, response, and retry limits.
- Separate an issuer-reported negative status from a network failure.
- Define the maximum age of cached status data and display that age to operators when useful.
- Prevent repeated retries from creating a denial-of-service problem for the issuer or status service.
- Route uncertain cases to a review or pending state instead of silently approving them.
- Alert on unusual increases in unknown, stale, malformed, or unavailable responses.
Scenario 4: Testing a wallet or presentation flow
Test the complete journey, not just the status endpoint. Present an active credential, then repeat the flow after expiration, revocation, suspension, issuer key changes, malformed status data, and a simulated network outage. Confirm that the wallet does not display a credential as usable merely because it remains stored locally. Also test user-facing explanations, accessibility, and recovery instructions. The digital identity wallet acceptance guide can help structure compatibility checks.
What to double-check
| Approach | Useful for | Operational points to verify |
|---|---|---|
| Credential expiration | Credentials that naturally become outdated | Clock handling, renewal flow, missing dates, and whether expiry alone is sufficient for the risk level |
| Issuer status endpoint | Direct status decisions and controlled issuer workflows | Availability, authentication, rate limits, response integrity, caching, and correlation exposure |
| Privacy-preserving status list | Large-scale status distribution with reduced direct lookup | List integrity, index handling, update frequency, bit or entry interpretation, and linkability risks |
| Revocation registry | Credential ecosystems with an established registry model | Registry trust, update propagation, recovery, key management, and behavior during registry downtime |
| Temporary suspension | Cases where acceptance may resume after review | Allowed duration, reactivation authority, user notification, and distinction from permanent revocation |
Confirm that the verifier checks the status mechanism specified by the credential profile, not an unrelated endpoint supplied by presentation data. Validate issuer identity and authorization independently. If your workflow uses an API provider, ask how it maps unknown, stale, revoked, suspended, and unavailable results; these distinctions should remain visible in logs and controls. For audit preparation, see the digital identity verification audit checklist.
Review privacy at the protocol and operations levels. A status lookup can reveal that a particular person is presenting a credential at a particular time, especially when identifiers or network metadata are stable. Consider indirect retrieval, caching, batching, issuer-hosted alternatives, and data minimization where compatible with the chosen ecosystem. Do not retain credential contents simply because they were available during verification.
Common mistakes
- Checking only the signature. Cryptographic authenticity does not prove that the issuer still accepts the credential.
- Checking only expiration. A credential can be revoked before its expiration date or suspended temporarily.
- Failing open during an outage. Treating an unknown status as active creates an undocumented risk decision.
- Using an indefinite cache. Cached results need a documented freshness limit and invalidation strategy.
- Confusing suspension with revocation. These states may require different user messaging, remediation, and reissue procedures.
- Logging too much. Full credentials, identifiers, or status queries can create a secondary privacy and security risk.
- Ignoring wallet behavior. Wallets may cache credentials, support different proof formats, or handle status failures differently. Test the actual presentation path.
- Returning vague errors. “Verification failed” is insufficient for support and incident response. Use stable internal reason codes while keeping external messages proportionate.
When to revisit
Review the status-checking design before adding a new credential type, issuer, wallet, or verification API. Revisit it when the credential profile, status-list format, SDK, key-management process, cache policy, or trust framework changes. It should also be part of seasonal planning and release testing, particularly before periods when verification volume or support demand is expected to rise.
Use this short maintenance checklist:
- Run active, expired, revoked, suspended, unknown, stale, malformed, and unavailable test cases.
- Confirm that policy decisions and user-facing messages still distinguish those outcomes.
- Review status-service latency, error rates, cache age, and unusual lookup patterns.
- Check issuer and verifier key rotation, recovery, and incident contacts.
- Reassess data retention, correlation, and access controls with the current workflow.
- Update interoperability notes when wallet behavior, SDK support, or relevant digital identity standards change.
The practical goal is not to create a single permanent rule for every credential. It is to make each status decision explicit, testable, privacy-aware, and appropriate to the transaction. Keep the checklist with the verifier’s runbook, test it whenever workflows or tools change, and document the conditions under which an operator may approve, reject, or defer a presentation.