Credential status
Whether a credential is still valid, and how anyone finds out.
The states
| Status | Meaning |
|---|---|
active |
Valid |
revoked |
Withdrawn by the issuer. Permanent |
suspended |
Temporarily not valid, and may become active again |
expired |
Past its validity period |
How a verifier checks
Not by calling you, and not by calling DiligenceID's API.
Status is published in a status list — a compact, signed structure a verifier fetches and checks directly. That is what makes the model work:
- The verifier needs no relationship with the issuer.
- The issuer does not learn who checked, or when.
- Checking works even when your systems are down.
A verifier that had to call an API to check revocation would give the issuer a log of every place the holder presented their credential. The status list exists specifically to avoid that.
Checking status yourself
GET /v1.0/credentials/{credentialId}/status
Authorization: ApiKey did_test.abc.xyz
Scope: credentials.read. This is for your own systems — reporting, support, reconciliation. A verifier does
not use it.
Revoking
POST /v1.0/credentials/{credentialId}/revoke
Scope: credentials.revoke.
Revocation is permanent. There is no un-revoke operation. If a credential was revoked in error, issue a new one — which is a new credential with a new identifier, not the old one restored.
That asymmetry is intentional. A verifier that saw a credential go from revoked back to active could not treat revocation as meaningful.
Propagation
Revocation takes effect when the status list is next published, and a verifier sees it when they next fetch the list. This is not instantaneous, and any revocation mechanism has this property — a verifier caching a status list is behaving correctly.
If your risk model needs certainty at the moment of use, do not rely on revocation timing alone. Combine it with a short credential lifetime, so a stale status list can only be stale for so long.
What DiligenceID does not have
The contents of an issued credential. It is held by the holder. There is no endpoint that returns it, because there is nothing to return.
What is retained is enough to answer "is this still valid?" — which is the status. A platform holding every credential it ever issued would be a far more attractive target than one holding their status.