Skip to main content

Manage credential status

Learn how to manage credentials through their lifecycle.

Learn about the lifecycle of issued credentials, including how credential states are reflected in the system and how to manage the validity of an issued credential.

Credential validity​

When issuing a credential the issuer is making assertions about a subject. In making these claims, the issuer takes on a certain responsibility for the truth of these claims. But it's important to recognize that the responsibility holds not just at the time of issuance but for as long as the credential can be used by the holder.

Since verifiers and holders rely on the asserted claims of a credential, it is important that issuers use the mechanisms available to them to maintain accurate validity of issued credentials. If the claims asserted are no longer true, the issuer must update the credential accordingly. Active management of credential validity creates trust in the issuer and in the identity ecosystem.

Credential states in the system​

To help you manage credentials and credential validity, credentials in the system have state representations to reflect where they are in the lifecycle and their current validity status. Credentials issued by the system exist in one of eight states:

Credentials states - issuer

The issuer calls the create-credential endpoint (CREATED) and then calls the issue-credential endpoint to generate the share endpoint URL (PENDING). The holder uses the share endpoint URL to connect to the offer (OFFERED).

From the offered state, there are three possible state changes:

  • The holder accepts the offered credential (ACCEPTED)
    • The credential is signed in this state, not before
    • The credential is valid in this state, and can be used by the holder
    • Once accepted, the credential remains in this state until the issuer suspends or revokes it (SUSPENDED, REVOKED)
  • The holder rejects the offered credential (REJECTED)
  • An error occurs (ERROR)
    • The offer times out before the holder makes a decision
    • Some other kind of error occurs
Notes and exceptions
  • Some exchange protocols do not notify the issuer when the holder accesses the offered credential. For these protocols, the credential state transitions directly from PENDING to other states, bypassing OFFERED.
  • Some suspension and revocation methods are not instantaneous because they rely on not renewing credentials which will expire at a later time. For these, the credential will be valid for the holder for some time while SUSPENDED or REVOKED for the issuer.
  • Once a credential's state becomes ERROR it cannot be returned to any other state.

Manage validity of an issued credential​

The schema of a credential defines whether an issued credential can be suspended or revoked, while the revocation method determines the mechanism for how a credential is suspended or revoked.

Choose a revocation method​

When creating a credential schema you define the revocation method that will be used to manage the validity of credentials issued with that schema.

When retrieving the configuration through the API, the revocationMethods capability of credential formats lists the revocation methods that can be used with each credential format.

Any credential schema can be created with the revocation method as NONE. Credentials issued with no revocation method cannot be suspended nor revoked and remain valid indefinitely, unless revocation is handled by another source or the credential includes some kind of inherent limitation such as an attribute specifying expiration time.

Enable suspension​

When creating a credential schema you can also enable suspension for certain credentials. For suspension to be enabled a revocation method must be chosen and that method must allow for suspension. When retrieving the configuration through the API, the operations capability of revocation methods lists whether the method enables suspension, revocation or both.

Suspend a credential​

Use suspension to make a credential invalid with the possibility of future reactivation.

For credentials that can be suspended, use the suspend endpoint. You can optionally specify a time when the credential should be reactivated automatically by the system. Otherwise the suspension remains in place until you either reactivate or revoke the credential.

info

The task SUSPEND_CHECK checks suspended credentials against their suspendEndDate and reactivates them once it has passed. When you build your application, decide how often and when you want to run this check.

Reactivate a credential​

A suspended credential can be reactivated at any time using the reactivation endpoint. Credentials which were suspended with a specified reactivation time will be reactivated at the specified time unless manually reactivated before.

Revoke a credential​

Revoke a credential to render it permanently invalid.

Instantaneous vs. delayed validity changes​

When suspending or revoking a credential, these changes in validity are sometimes instant and sometimes delayed, depending on the revocation method used. This is due to the nature of the mechanism used by the method.

There are two major kinds of revocation methods: list-based and expiration-based.

List-based methods involve publishing a list that reflects the validity status of credentials. Information about how to access the list and where in the list the credential's validity status can be found is put directly into the credential. During the verification process the verifier's system checks the list to get the latest validity status. This method produces virtually instantaneous suspension and revocation for the issuer since they manage the published list in real time.

Expiration-based methods involve the credential, either the credential itself or an extra credential attached to the original credential, having a short validity duration and then reissuing the credential shortly before it expires. In these methods the system is configured to reissue the credential according to configured durations unless you have suspended or revoked the credential. When you do suspend or revoke a credential that uses one of these methods, you are instructing the system to not reissue the credential the next time the holder's wallet requests a reissuance. When you suspend or revoke, the credential remains valid in the holder's wallet until it expires.

Expiration-based methods include any credential in the ISO mdoc format and any credential that uses the LVVC revocation method. Timelines for expiration-based methods are fully configurable; configure the MDOC format for ISO mdocs and the LVVC revocation method to set desired durations.

Related guide: System configuration

Credential deletion​

Conditions for credential deletion:

  • If the credential is in state ACCEPTED and its schema includes a revocation method, the credential cannot be deleted.
  • If the revocation method is NONE then the credential can be deleted in any state.

The history action DELETED is recorded and the credential is no longer retrievable.

Deletion of a credential has no impact on a holder's ability to keep and use the credential.