Skip to main content

Credential lifecycle

A credential record is the stable, unified representation of a credential across its whole lifecycle — covering both in-person issuances and pending remote issuance requests. Each record is identified by the credentialRecordId returned when an issuance is created, and this identifier remains constant from issuance through to revocation and expiry.

Both in-person and remote issuances are visible together in the Credentials view in Composer, which provides a unified lifecycle view across all issuance methods. The API exposes the same unified view through the findCredentialRecords query, and the deprovisionCredential mutation for ending a credential's life regardless of its current state.

Query credential records​

Use the findCredentialRecords query to retrieve a unified view of credential records. The optional where argument supports filtering by identity, contract, issuance method, status, and creation date, with AND/OR composition.

FindCredentialRecords query
query FindCredentialRecords($where: CredentialRecordWhere, $limit: PositiveInt, $offset: NonNegativeInt) {
  findCredentialRecords(where: $where, limit: $limit, offset: $offset) {
    id
    credentialRecordStatus
    issuanceMethod
    createdAt
  }
}

The excludeDeprovisionedOlderThanDays filter excludes records in a deprovisioned state (such as revoked, expired, offerExpired, offerCancelled, offerFailed, issuanceFailed, identityNotVerified, or issuanceExpired) whose deprovisioning event occurred more than the specified number of days ago. Records that are not deprovisioned are never excluded, and omitting the field returns all records regardless of age.

Example variables: only active records, plus those deprovisioned within the last 30 days
{
  "where": {
    "identityId": "<identity ID>",
    "excludeDeprovisionedOlderThanDays": 30
  },
  "limit": 100
}
VO IconVO Tip

Use credentialRecordCount with the same where argument to retrieve the total number of matching records — useful for pagination.

Deprovision a credential​

Use the deprovisionCredential mutation to revoke or cancel a credential regardless of where it currently sits in its lifecycle, without needing to know its current state. The credentialRecordId argument is the id field returned by each findCredentialRecords result (also the credentialRecordId returned when the issuance was created). Given a credentialRecordId, the mutation:

  • Revokes the credential if it has been issued to a wallet.
  • Cancels the remote issuance request if it is a pending offer.
  • Cancels the in-person issuance offer if it has not been redeemed.

The operation is idempotent — calling it on an already-deprovisioned credential succeeds and returns the current status. It returns an error when the credentialRecordId does not resolve to a known record. The mutation returns the resulting CredentialRecordStatus.

DeprovisionCredential mutation
mutation DeprovisionCredential($credentialRecordId: ID!) {
  deprovisionCredential(credentialRecordId: $credentialRecordId)
}
Example response
{
  "data": {
    "deprovisionCredential": "revoked"
  }
}
Permission required

deprovisionCredential requires the credentials.revoke application role. See Onboarding apps for details on assigning roles.