Check the state of a stored personhood credential

Use PresentationService.checkCredentialState when your backend has stored a credential JWT and needs a lightweight state check before deciding what the user may do.

const state = await presentation.checkCredentialState({
  credentialJwt: storedCredential.credentialJwt,
});

checkCredentialState returns a state object instead of throwing for expected status-list or parsing problems:

type CredentialState = {
  expiration: boolean;
  revocation: 'not_revoked' | 'revoked' | 'unknown';
  statusListLifecycle: 'active' | 'retired' | 'sealing' | 'sealed' | 'unknown';
  checkedAt: string;
};

The method checks whether the credential is expired. When the credential has a usable status-list reference and the SDK has a status-list client, it also checks whether the credential is revoked. Expiration and revocation are independent: an expired credential may also be revoked.

checkCredentialState is not a replacement for full credential verification. Use verifyCredential or verifySubmission when issuing or first accepting a credential, and use the state check for subsequent stored-credential decisions.

Apply the state to app logic

Credential revocation is one-way. Once a credential is revoked, it cannot become not_revoked again.

How your application uses a credential state depends on its risk model. In the general case, a credential is valid only when it is neither expired nor revoked. The App Registry developer gate follows this model: a test wallet is accepted only while its gate credential remains valid.

A Developer Forum might use a Human credential to confirm that a new account is created by a person rather than a bot. Under this policy, the credential’s expiration does not invalidate the account because personhood is verified only at registration. The forum may still restrict posting and commenting if the stored credential is revoked.

A revoked credential is no longer valid. In general, do not infer why it was revoked. However, a system may define a specific meaning for revocation. For example, if issuing a credential for a new account revokes the credential associated with an earlier account, restricting posting and commenting on the earlier account can help prevent sockpuppet-account abuse.

The same account-creation flow may have different requirements in another product. For example, a social-media service may require proof of personhood only at registration and again after a long period of inactivity. In that case, the credential is a one-time proof: verify it fully at the required moment, then retain the result according to your policy. Its later expiration or revocation does not affect the account unless your policy says it should.

Status-List Lifecycle and Its Effect on the Credential

statusListLifecycle describes the lifecycle of the status list used by the credential:

When statusListLifecycle is sealed, the status list is final and no longer accepts revocations. If a credential is not_revoked when its list is sealed, its revocation state will remain not_revoked for that list. If your application requires a credential that can still be revoked, ask the user to submit a newly issued credential.

The SDK returns unknown when the credential cannot be parsed, has no usable status-list reference, no statusListUrl or status-list client is configured, or status-list retrieval or verification fails. If this continues to occur, check the statusListUrl in the PresentationService configuration. It may have been removed or changed accidentally.

Store and re-check state

Store the original JWT only on the backend. Re-run checkCredentialState immediately before a protected action, and record checkedAt in your authorization audit record. A previous not_revoked result is not permanent: issuing a replacement credential can revoke an older credential in the same context.

Credential state and same-context revocation

When credential-issue needs to create a new presentation-definition credential, it first checks for an existing credential that can be reused. If it creates a replacement, matching active credentials in the same context are revoked before the new credential is saved. The replacement then becomes the current credential for that context.

Your application supplies the following context attributes. Use a stable value for subject when later requests should replace the credential for the same account or resource.

credential-issue also uses server-derived tenant and credential-anchor values when it identifies matching credentials. Your application does not need to configure those values.