API Reference
API endpoints for inspecting the credentials that have already been issued to a holder
Credential update is offered as an open beta preview feature and is not generally available yet. It is available on all tenants, and its behavior may change in a way that breaks existing integrations before it becomes generally available.
These endpoints let you inspect the credentials that have already been issued to a holder, so you can find the credential bundle to target when you update a credential, and withdraw a credential you no longer want the holder to use. A credential reference groups every copy of a holder's credential of a given type. A credential bundle is one of those copies as it sits in one wallet instance, and it carries the claimSetId it was issued for, if any. A bundle can hold several instances of the credential, such as the new versions issued by each update. See Credential bundle.
The update itself is created through the credential offer endpoint, not through these endpoints.
Credential references
Retrieve all credential references for a user
Retrieve all credential references associated with the specified user.
A credential reference is a logical identifier for a credential, independent of any particular wallet or device. When a credential is issued to a user, it may be stored in multiple wallets or on multiple devices. Each stored instance is a separate copy, but all copies represent the same underlying credential.
The credential reference stays the same across all of these instances, allowing issuers to consistently identify and interact with the credential regardless of where the user holds it.
Roles
Analytics Events
bearerAuthAuthorizationBearer <token>userId*stringThe user ID represents a unique identifier for a user in the system. The user ID is generated by the system when a user is created, and is returned in the response when retrieving users.
uuidlimit?numberRange size of returned list.
1 <= value <= 1000100cursor?stringStarting point for the list of entries.
Credential references retrieved
application/json- response
data?array<>nextCursor?stringcurl -X GET 'https://example.vii.au01.mattr.global/v1/users/41458e5a-9092-40b7-9a26-d4eb43c5792f/credential-references'{ "data": [ { "userId": "41458e5a-9092-40b7-9a26-d4eb43c5792f", "credentialReferenceId": "a248d6c9-3f5e-4b2a-9c1e-2f3b4c5d6e7f", "credentialProfile": "mobile", "credentialType": "org.iso.18013.5.1.mDL", "claimSetId": "claim-set-1" } ], "nextCursor": "string"}Retrieve a credential reference
Retrieve the specified credential reference.
A credential reference is a logical identifier for a credential, independent of any particular wallet or device. When a credential is issued to a user, it may be stored in multiple wallets or on multiple devices. Each stored instance is a separate copy, but all copies represent the same underlying credential.
The credential reference stays the same across all of these instances, allowing issuers to consistently identify and interact with the credential regardless of where the user holds it.
Roles
Analytics Events
bearerAuthAuthorizationBearer <token>credentialReferenceId*stringThe credential reference ID represents a link between a user and a credential profile, and is used to manage credentials for the user. Each credential reference ID is unique to a combination of user, credential type and, when the credential is issued against a claim set, claim set identifier. It stays the same across every device the credential is claimed on and every time the credential is updated, and is returned in the response when retrieving credential references.
uuidCredential reference retrieved
application/json- response
userId*stringThe user ID that owns this credential reference.
uuidcredentialReferenceId*stringThe credential reference ID represents a link between a user and a credential profile, and is used to manage credentials for the user. Each credential reference ID is unique to a combination of user, credential type and, when the credential is issued against a claim set, claim set identifier. It stays the same across every device the credential is claimed on and every time the credential is updated, and is returned in the response when retrieving credential references.
credentialProfile*stringThe credential profile represents the type of credential that is associated with the credential reference. This is typically used to group credentials of the same type together, and can be used by the client to determine which credential to request when multiple credentials are associated with a credential reference.
credentialType*stringThe credential type represents the specific type of credential that is associated with the credential reference. This is typically used to identify the format or standard of the credential.
claimSetId?stringThe claim set identifier the credential reference was issued for.
curl -X GET 'https://example.vii.au01.mattr.global/v1/users/credential-references/a248d6c9-3f5e-4b2a-9c1e-2f3b4c5d6e7f'{ "userId": "41458e5a-9092-40b7-9a26-d4eb43c5792f", "credentialReferenceId": "a248d6c9-3f5e-4b2a-9c1e-2f3b4c5d6e7f", "credentialProfile": "mobile", "credentialType": "org.iso.18013.5.1.mDL", "claimSetId": "claim-set-1"}Credential bundles
Retrieve all credential bundles for a credential reference
Retrieve all credential bundles associated with the specified credential reference. A credential bundle is one credential, for one credential type and claim set, as it sits in one wallet instance. It can hold several instances of that credential, such as the new versions issued by each update.
Roles
Analytics Events
bearerAuthAuthorizationBearer <token>credentialReferenceId*stringThe credential reference ID represents a link between a user and a credential profile, and is used to manage credentials for the user. Each credential reference ID is unique to a combination of user, credential type and, when the credential is issued against a claim set, claim set identifier. It stays the same across every device the credential is claimed on and every time the credential is updated, and is returned in the response when retrieving credential references.
uuidlimit?numberRange size of returned list.
1 <= value <= 1000100cursor?stringStarting point for the list of entries.
Credential bundles retrieved
application/json- response
data?array<>nextCursor?stringcurl -X GET 'https://example.vii.au01.mattr.global/v1/users/credential-references/a248d6c9-3f5e-4b2a-9c1e-2f3b4c5d6e7f/credential-bundles'{ "data": [ { "userId": "41458e5a-9092-40b7-9a26-d4eb43c5792f", "id": "e123f4a5-6b7c-8901-2345-67890abcdef2", "issuanceProtocol": "openid4vci", "credentialReferenceId": "a248d6c9-3f5e-4b2a-9c1e-2f3b4c5d6e7f", "credentialConfigurationId": "b123c4d5-6e7f-8901-2345-67890abcdef1", "credentialProfile": "mobile", "credentialType": "org.iso.18013.5.1.mDL", "sessionId": "string", "walletId": "com.example.wallet", "walletInstanceId": "d654c3b2-1a0f-9e8d-7c6b5a4f3e2d", "offerId": "f567e8d9-0a1b-2345-6789-0abcdef12345", "claimSetId": "claim-set-1", "state": "active" } ], "nextCursor": "string"}Retrieve a credential bundle
Retrieve the specified credential bundle for the specified user. A credential bundle is one credential, for one credential type and claim set, as it sits in one wallet instance. It can hold several instances of that credential, such as the new versions issued by each update.
Roles
Analytics Events
bearerAuthAuthorizationBearer <token>credentialBundleId*stringThe credential bundle ID represents a unique identifier for a credential bundle. The credential bundle ID is generated by the system when a credential bundle is created, and is returned in the response when retrieving credential bundles.
uuidinclude-inactive?booleanWhen set to true, credentials with a status of invalid are included in the response.
falseCredential bundle retrieved
application/json- response
userId*stringThe user ID that owns this credential bundle.
uuidid*stringThe credential bundle ID uniquely identifies one credential, for one credential type and claim set, as it sits in one wallet instance. The credential bundle ID is generated by the system when a credential bundle is created, and is returned in the response when retrieving credential bundles.
uuidissuanceProtocol*"openid4vci"The issuance protocol represents the protocol that was used to issue the credentials in this bundle.
"openid4vci"credentialReferenceId*stringThe credential reference ID of the credential bundle.
credentialConfigurationId*stringThe credential configuration ID represents the credential configuration that was used to issue the credentials in this bundle.
uuidcredentialProfile*stringThe credential profile represents the profile of the credentials in this bundle.
credentialType*stringThe credential type represents the type of the credentials in this bundle.
sessionId?stringThe session ID represents the issuance OpenID session during which the credentials in this bundle were issued.
walletId?stringThe wallet ID represents the OpenID Client of the wallet application to which the credentials in this bundle were issued.
walletInstanceId?stringThe wallet instance ID represents the specific instance of the wallet application to which the credentials in this bundle were issued.
offerId?stringThe offer ID represents the credential offer that was used to issue the credentials in this bundle.
uuidclaimSetId?stringThe claim set identifier the credential bundle was issued for.
state*stringThe state represents the current status of the credential bundle. This indicates whether the credentials in the bundle are active and can be used, or whether the bundle has been unlinked and its credentials can no longer be used.
"active""unlinked"credentials?array<>The list of credentials that are part of this credential bundle.
curl -X GET 'https://example.vii.au01.mattr.global/v1/users/credential-bundles/e123f4a5-6b7c-8901-2345-67890abcdef2'{ "id": "e123f4a5-6b7c-8901-2345-67890abcdef2", "userId": "41458e5a-9092-40b7-9a26-d4eb43c5792f", "issuanceProtocol": "openid4vci", "credentialReferenceId": "a248d6c9-3f5e-4b2a-9c1e-2f3b4c5d6e7f", "credentialConfigurationId": "b123c4d5-6e7f-8901-2345-67890abcdef1", "credentialProfile": "mobile", "credentialType": "org.iso.18013.5.1.mDL", "sessionId": "c987d6e5-4b3a-210f-9e8d-7c6b5a4f3e2d", "walletId": "com.example.wallet", "walletInstanceId": "d654c3b2-1a0f-9e8d-7c6b5a4f3e2d", "offerId": "f567e8d9-0a1b-2345-6789-0abcdef12345", "state": "active", "credentials": [ { "credentialId": "552b35fe-a3ed-4c33-8c3c-64810c712323", "devicePublicKey": { "kty": "EC", "crv": "P-256", "x": "11qYAYKxCrfVS_7TyWQHOg7hcvPapiMlrwIaaPcHURo" }, "namespaces": { "org.iso.18013.5.1": { "given_name": { "digestID": 0, "digest": "8GWbUyIRA2xATs5ILEa0fVZF1QQt4JL5gG2aCtVsazU" }, "family_name": { "digestID": 1, "digest": "R4jk/m0wX9KhENp7DVPr9AM7Hz+CJoEJNKJRQo92FCI" } } }, "msoHash": "OsPO++ARsvvJYswmuzN8E3rxN+jAkbWbxhqVIOfM1Go", "issuedDate": "2025-06-28T12:34:56.000Z", "validFrom": "2025-06-30T12:00:00.000Z", "validUntil": "2025-07-30T12:00:00.000Z", "status": "valid" } ]}Search credential bundles
Search across every credential bundle issued from your tenant, optionally filtered by claim set identifier and/or state. Unlike the other credential bundle endpoints, this search is not scoped to a single user or credential reference. When state is omitted, only active bundles are returned.
Claim set identifiers are offered as an open beta preview feature and are not generally available yet. They are available on all tenants, and their behavior may change in a way that breaks existing integrations before they become generally available.
Roles
Analytics Events
bearerAuthAuthorizationBearer <token>The search criteria
application/json- body
claimSetId?stringFilter credential bundles to only those issued for the specified claim set.
1 <= length <= 255state?array<>Filter bundles by state. Defaults to ["active"] when omitted. Rejected with a 400 response if provided as an empty array.
1 <= itemslimit?numberRange size of returned entries, default 100
1 <= value <= 1000cursor?stringStarting point for the range of entries
Credential bundles retrieved
application/json- response
data?array<>nextCursor?stringcurl -X POST 'https://example.vii.au01.mattr.global/v1/users/credential-bundles/search' \ -H 'Content-Type: application/json' \ -d '{ "claimSetId": "claim-set-1", "limit": 100}'{ "data": [ { "userId": "41458e5a-9092-40b7-9a26-d4eb43c5792f", "id": "e123f4a5-6b7c-8901-2345-67890abcdef2", "issuanceProtocol": "openid4vci", "credentialReferenceId": "a248d6c9-3f5e-4b2a-9c1e-2f3b4c5d6e7f", "credentialConfigurationId": "707e920a-f342-443b-ae24-6946b7b5033e", "credentialProfile": "mobile", "credentialType": "org.iso.18013.5.1.mDL", "claimSetId": "claim-set-1", "state": "active" } ], "nextCursor": "Y3JlYXRlZEF0PTIwMjAtMDgtMjVUMDY6NDY6MDkuNTEwWiZpZD1h"}Unlinking
Unlinking withdraws credentials that have already been issued. The bundle's state becomes unlinked, the credentials it holds are revoked, and the refresh token issued for its session is invalidated. An unlinked bundle can no longer be targeted for an update, so unlinking is how you take a credential out of service rather than reissuing it.
Unlinking is permanent and cannot be reversed. To put a credential back in the holder's wallet, issue a new one.
Unlink a single bundle to withdraw the credentials on one device. Unlink the credential reference to withdraw them from every device the user holds that credential on.
Unlink a credential bundle
Unlink the specified credential bundle. Unlinking sets the bundle's state to unlinked, revokes the credentials it holds, and invalidates the refresh token issued for the bundle's issuance session. Use this to withdraw the credentials issued to a specific device or wallet instance.
An unlinked bundle cannot be targeted for a credential update. Unlinking is permanent and cannot be reversed. To put a credential back in the holder's wallet, issue a new one.
Credential update is offered as an open beta preview feature and is not generally available yet. It is available on all tenants, and its behavior may change in a way that breaks existing integrations before it becomes generally available.
Roles
Analytics Events
bearerAuthAuthorizationBearer <token>credentialBundleId*stringThe credential bundle ID represents a unique identifier for a credential bundle. The credential bundle ID is generated by the system when a credential bundle is created, and is returned in the response when retrieving credential bundles.
uuidCredential bundle unlinked
application/json- response
userId*stringThe user ID that owns this credential bundle.
uuidid*stringThe credential bundle ID uniquely identifies one credential, for one credential type and claim set, as it sits in one wallet instance. The credential bundle ID is generated by the system when a credential bundle is created, and is returned in the response when retrieving credential bundles.
uuidissuanceProtocol*"openid4vci"The issuance protocol represents the protocol that was used to issue the credentials in this bundle.
"openid4vci"credentialReferenceId*stringThe credential reference ID of the credential bundle.
credentialConfigurationId*stringThe credential configuration ID represents the credential configuration that was used to issue the credentials in this bundle.
uuidcredentialProfile*stringThe credential profile represents the profile of the credentials in this bundle.
credentialType*stringThe credential type represents the type of the credentials in this bundle.
sessionId?stringThe session ID represents the issuance OpenID session during which the credentials in this bundle were issued.
walletId?stringThe wallet ID represents the OpenID Client of the wallet application to which the credentials in this bundle were issued.
walletInstanceId?stringThe wallet instance ID represents the specific instance of the wallet application to which the credentials in this bundle were issued.
offerId?stringThe offer ID represents the credential offer that was used to issue the credentials in this bundle.
uuidclaimSetId?stringThe claim set identifier the credential bundle was issued for.
state*stringThe state represents the current status of the credential bundle. This indicates whether the credentials in the bundle are active and can be used, or whether the bundle has been unlinked and its credentials can no longer be used.
"active""unlinked"curl -X POST 'https://example.vii.au01.mattr.global/v1/users/credential-bundles/e123f4a5-6b7c-8901-2345-67890abcdef2/unlink'{ "userId": "41458e5a-9092-40b7-9a26-d4eb43c5792f", "id": "e123f4a5-6b7c-8901-2345-67890abcdef2", "issuanceProtocol": "openid4vci", "credentialReferenceId": "a248d6c9-3f5e-4b2a-9c1e-2f3b4c5d6e7f", "credentialConfigurationId": "707e920a-f342-443b-ae24-6946b7b5033e", "credentialProfile": "mobile", "credentialType": "org.iso.18013.5.1.mDL", "state": "unlinked"}Unlink a credential reference
Unlink every credential bundle held against the specified credential reference. Each bundle has its state set to unlinked, the credentials it holds are revoked, and the refresh token issued for its session is invalidated. Use this to withdraw a credential from every device the user holds it on, rather than one device at a time.
The response lists the bundles that were unlinked. Bundles that were already unlinked are left alone and are not returned, so a reference with nothing left to unlink returns an empty list.
An unlinked bundle cannot be targeted for a credential update. Unlinking is permanent and cannot be reversed. To put a credential back in the holder's wallet, issue a new one.
Credential update is offered as an open beta preview feature and is not generally available yet. It is available on all tenants, and its behavior may change in a way that breaks existing integrations before it becomes generally available.
Roles
Analytics Events
bearerAuthAuthorizationBearer <token>credentialReferenceId*stringThe credential reference ID represents a link between a user and a credential profile, and is used to manage credentials for the user. Each credential reference ID is unique to a combination of user, credential type and, when the credential is issued against a claim set, claim set identifier. It stays the same across every device the credential is claimed on and every time the credential is updated, and is returned in the response when retrieving credential references.
uuidCredential reference unlinked
application/json- response
credentialBundles*array<>The credential bundles that were unlinked by this request. Empty when the credential reference had no bundles left to unlink.
curl -X POST 'https://example.vii.au01.mattr.global/v1/users/credential-references/a248d6c9-3f5e-4b2a-9c1e-2f3b4c5d6e7f/unlink'{ "credentialBundles": [ { "userId": "41458e5a-9092-40b7-9a26-d4eb43c5792f", "id": "e123f4a5-6b7c-8901-2345-67890abcdef2", "issuanceProtocol": "openid4vci", "credentialReferenceId": "a248d6c9-3f5e-4b2a-9c1e-2f3b4c5d6e7f", "credentialConfigurationId": "707e920a-f342-443b-ae24-6946b7b5033e", "credentialProfile": "mobile", "credentialType": "org.iso.18013.5.1.mDL", "state": "unlinked" } ]}Related API references
- Create a credential offer: Create the pre-authorized offer that delivers the update, using
credentialBundleId - Users: Manage the users that credentials are issued to
How would you rate this page?
Last updated on