Credential Update

Overview

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 enables

• 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 concepts

Credential reference

A credential reference represents a logical grouping of credential instances for a specific credential type issued to a user. It acts as an identifier for "this user's driver's license" or "this user's employee ID," across all copies.

For example, if a user receives their driver's license on more than one device, each of those instances belongs to the same credential reference. This allows issuers to:

• Track all instances of a specific credential type for a user
• Manage credentials at a logical level rather than tracking individual device instances

The credential reference identifier is derived from the user ID and the credential type (doctype), so it is stable for a given user and credential type. When the credential is issued against a claim set identifier, that identifier forms part of the derivation as well, so each claim set the user holds for the same credential type resolves to its own credential reference.

Credential bundle

A credential bundle represents credentials issued together as part of the same issuance session, typically to a specific device or wallet instance.

When a wallet requests and receives credentials, all credentials issued in that single transaction form a bundle associated with:

• A specific issuance session
• A specific wallet instance (identified by wallet ID and instance ID)
• The credential offer that initiated the issuance (if applicable)
• The credential configuration used for issuance

A bundle is the unit you target when you update a credential. Updating a bundle leaves the user's other bundles for the same credential reference untouched, so a credential held on one device can be updated independently of a copy held on another.

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 hierarchy

User
  └── Credential Reference (e.g., "Driver's License")
        ├── Credential Bundle (Phone - Session 1)
        │     ├── Credential Instance (MSO v1)
        │     └── Credential Instance (MSO v2 - updated)
        └── Credential Bundle (Tablet - Session 2)
              └── Credential Instance (MSO v1)

How an update is delivered

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 updates

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 references

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

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

Retrieving credential bundles

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 bundle

Retrieve one bundle, including the credential instances inside it:

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

Finding a bundle by claim set

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 updates

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.

Considerations

Credential data

• 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 security

• 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.