Credential Update

OverviewCopy Anchor Link

Credential Update enables a holder to obtain a new version of a credential they already hold, without re-enrolling and without the user re-authenticating. The new credential is issued into the bundle the holder already has rather than into a new one, and the wallet replaces the copy it holds, so the holder ends up with a single, current credential.

This keeps credential data accurate as your system of record changes, extends MSO validity before a credential expires, and lets you manage the lifecycle of a credential you have already issued.

This is supported in MATTR VII's issuance capability alongside our Holder SDKs.

What this enablesCopy Anchor Link

• Keep credential data in sync with systems of record: Reissue a credential when the underlying data changes, so the holder is not carrying stale claims.
• Extend expiring MSOs: Issue a fresh MSO with a new validity period before the holder's current credential expires.
• Correct a credential without invalidating it: Remove or amend a single claim, such as a driving privilege, while the holder keeps a usable credential. See Revoking a driving privilege.
• Update without a new enrollment: The holder does not repeat the authentication or identity check they completed at first issuance.

Core conceptsCopy Anchor Link

The examples in this section follow one family. Alex keeps birth certificates in their wallet for themselves and their children, Sam and Riley. Later, Sam's certificate needs a name correction.

Credential referenceCopy Anchor Link

A credential reference is "this user's credential of this type", no matter which device it is on. For example, "Alex's copy of Sam's birth certificate". Its identifier is credentialReferenceId.

A credential reference is unique to a user and a credential type (doctype). It stays the same across every device the credential is claimed on, and every time the credential is updated. When a user holds several credentials of the same type, such as one birth certificate per child, each is issued against its own claim set identifier, and each gets its own credential reference.

Credential bundleCopy Anchor Link

A credential bundle is one credential as it sits in one wallet. It is created when a wallet claims the credential, and it is tied to:

• The issuance session and the credential offer that started it (if applicable)
• The wallet instance that claimed it (identified by wallet ID and instance ID)
• The credential configuration used for issuance

If Alex installs the wallet on a phone and a tablet, Sam's certificate has one credential reference and two bundles. Its identifier is credentialBundleId.

A bundle is the unit you target when you update a credential. Updating Sam's certificate on the phone leaves the copy on the tablet untouched.

A bundle is also the unit you withdraw. Unlinking a bundle revokes the credentials it holds and takes it out of service, and unlinking the credential reference does that to every bundle under it. See Unlinking.

Relationship hierarchyCopy Anchor Link

User (Alex)
  └── Credential Reference (Sam's birth certificate)
        ├── Credential Bundle (Phone - Session 1)
        │     ├── Credential Instance (MSO v1)
        │     └── Credential Instance (MSO v2 - updated)
        └── Credential Bundle (Tablet - Session 2)
              └── Credential Instance (MSO v1)

Terms shared with claim setsCopy Anchor Link

Credential references and bundles are also used by Claim sets, which let one user hold several credentials of the same type. You can update credentials without using claim sets. Two claim set terms come up when you update such a credential:

• Claim set identifier: Your own record number for one credential, such as BC-1002 for Sam's certificate. Each bundle issued for a claim set carries it as claimSetId, so you can find the bundle to update. See Claim set identifier.
• Credential identifier: The value the wallet uses to request one specific credential when an offer contains several. See Credential identifier.

How an update is deliveredCopy Anchor Link

An update is delivered through a pre-authorized credential offer that targets an existing credential bundle. Your backend creates an offer the same way it does for a first issuance, naming the bundle you want to update. When the wallet claims that offer, the newly issued credential replaces the credential in that bundle instead of creating a new one.

See Update via pre-authorized offer for the flow, the validation MATTR VII applies, and the request format.

Updates are always issuer-initiated. MATTR VII does not compare the credential you are about to issue against the one the holder already has when you create the offer, so nothing is suppressed at that point. If you only want to reissue when your data has actually changed, evaluate that condition against your own system of record and create the offer only when an update is warranted. The credential request itself does have a conditional mode that a wallet can opt into, which can stop an update from reaching the holder. See Deciding when to update.

Managing updatesCopy Anchor Link

To create an update offer you need the credentialBundleId of the bundle you are targeting. If you did not persist it at first issuance, resolve it through the API.

Listing credential referencesCopy Anchor Link

Retrieve all credential references for a user to see which credentials they have been issued:

GET /v1/users/{userId}/credential-references

Retrieving credential bundlesCopy Anchor Link

Retrieve all credential bundles for a credential reference. Each bundle in the response carries its credentialBundleId:

GET /v1/users/credential-references/{credentialReferenceId}/credential-bundles

Retrieving a single credential bundleCopy Anchor Link

Retrieve one bundle, including the credential instances inside it:

GET /v1/users/credential-bundles/{credentialBundleId}

Finding a bundle by claim setCopy Anchor Link

If the credential was issued against a claim set identifier, each bundle carries the claimSetId it was issued for, and you can search bundles across the tenant by that identifier:

POST /v1/users/credential-bundles/search

See Find credentials by claim set.

See the API reference for the full request and response detail.

Triggering updatesCopy Anchor Link

Timing is entirely issuer-driven. You decide when an update is due, for example when a credential is approaching the end of its validity period, or when your system of record reports a change to the data behind it.

Because the update is carried by an ordinary credential offer, you share the resulting offer URI with the holder exactly as you would for a first issuance.

ConsiderationsCopy Anchor Link

Credential dataCopy Anchor Link

• The updated credential is built the same way as it is at initial issuance: from the claims supplied with the update, any claims persisted against the user, and any configured claims source.
• Validity dates come from the credential configuration and are applied at issuance, so every updated credential carries a new validity period.
• The credential that the update supersedes is not revoked automatically. It remains valid until it expires. If the older credential must stop being accepted, revoke it explicitly. This requires the credential to have been issued as revocable, so see Revocation for what that involves.

Privacy and securityCopy Anchor Link

• Claiming an update requires a valid access token, maintaining the same authorization model as initial credential issuance.
• MATTR VII confirms that the wallet claiming the update is the wallet instance the bundle is bound to, so an update offer cannot be redirected to a different device.