API Reference
API endpoints for inspecting the credentials that have already been issued to a holder
Credential update is offered as a closed beta preview feature and is not generally available yet. It is enabled per tenant, and its behavior may change in a way that breaks existing integrations before it becomes generally available. If you are interested in trying this feature, please contact us to have it enabled on your tenant.
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 represents the credentials issued together in a single issuance session, to a single wallet instance.
The update itself is created through the credential offer endpoint, not through these endpoints.
Credential references
Retrieve all credential references for a user
/v1/users/{userId}/credential-referencesRetrieve 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
Authorization
bearerAuth In: header
Path Parameters
The 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.
uuidQuery Parameters
Range size of returned list.
1 <= value <= 1000100Starting point for the list of entries.
Response Body
application/json
application/json
curl -X GET "https://example.com/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
/v1/users/credential-references/{credentialReferenceId}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
Authorization
bearerAuth In: header
Path Parameters
The credential reference ID represents a link between a user and a credential profile, and is used to manage credentials for the user. The credential reference ID is generated by the system when a credential reference is created, and is returned in the response when retrieving credential references.
uuidResponse Body
application/json
application/json
application/json
curl -X GET "https://example.com/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
/v1/users/credential-references/{credentialReferenceId}/credential-bundlesRetrieve all credential bundles associated with the specified credential reference. A credential bundle represents a group of credentials that were issued together as part of the same issuance session.
Roles
Analytics Events
Authorization
bearerAuth In: header
Path Parameters
The credential reference ID represents a link between a user and a credential profile, and is used to manage credentials for the user. The credential reference ID is generated by the system when a credential reference is created, and is returned in the response when retrieving credential references.
uuidQuery Parameters
Range size of returned list.
1 <= value <= 1000100Starting point for the list of entries.
Response Body
application/json
application/json
application/json
curl -X GET "https://example.com/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
/v1/users/credential-bundles/{credentialBundleId}Retrieve the specified credential bundle for the specified user. A credential bundle represents a group of credentials that were issued together as part of the same issuance session.
Roles
Analytics Events
Authorization
bearerAuth In: header
Path Parameters
The 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.
uuidQuery Parameters
When set to true, credentials with a status of invalid are included in the response.
falseResponse Body
application/json
application/json
application/json
curl -X GET "https://example.com/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
/v1/users/credential-bundles/searchSearch 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 a closed beta preview feature and are not generally available yet. They are enabled per tenant, and their behavior may change in a way that breaks existing integrations. If you are interested in trying this feature, please contact us.
Roles
Analytics Events
Authorization
bearerAuth In: header
Request Body
application/json
The search criteria
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/json
application/json
curl -X POST "https://example.com/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
/v1/users/credential-bundles/{credentialBundleId}/unlinkUnlink 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 a closed beta preview feature and is not generally available yet. It is enabled per tenant, and its behavior may change in a way that breaks existing integrations. If you are interested in trying this feature, please contact us.
Roles
Analytics Events
Authorization
bearerAuth In: header
Path Parameters
The 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.
uuidResponse Body
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/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
/v1/users/credential-references/{credentialReferenceId}/unlinkUnlink 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 a closed beta preview feature and is not generally available yet. It is enabled per tenant, and its behavior may change in a way that breaks existing integrations. If you are interested in trying this feature, please contact us.
Roles
Analytics Events
Authorization
bearerAuth In: header
Path Parameters
The credential reference ID represents a link between a user and a credential profile, and is used to manage credentials for the user. The credential reference ID is generated by the system when a credential reference is created, and is returned in the response when retrieving credential references.
uuidResponse Body
application/json
application/json
application/json
curl -X POST "https://example.com/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