---
title: Credential Verifications
description: The Credential Verification service receives, and responds to, requests for credential verification using Decentralized Identity Foundation Java Web Token Verifiable Credentials Presentation Profile (DIF JWT-VC Profile). The profile uses such open standards as:
component: pingone-api
page_id: pingone-api:credentials:credential-verifications
canonical_url: https://developer.pingidentity.com/pingone-api/credentials/credential-verifications.html
section_ids:
assigning-admin-roles-and-permissions-to-this-service: Assigning admin roles and permissions to this service
credential-verifications-session-data-model: Credential Verifications session data model
credential-verifications-credential-data-data-model: Credential Verifications credential data data model
credential-verifications-session-data-data-model: Credential Verifications session data data model
credential-verifications-error-object-data-model: Credential Verifications errors object data model
credential-verifications-error-codes: Credential Verifications error codes
response-codes: Response codes
---
# Credential Verifications
The Credential Verification service receives, and responds to, requests for credential verification using Decentralized Identity Foundation Java Web Token Verifiable Credentials Presentation Profile (DIF JWT-VC Profile). The profile uses such open standards as:
* World Wide Web Consortium (W3C) Decentralized Identifiers (DID) for core architecture, data model, and representations
* W3C Verifiable Credentials Data Model for the presentation data model
* DIF Presentation Exchange for credential request
* OpenID for Verifiable Presentations (OpenID4VP ID1) as the base protocol for transportation
Use of [these standards](https://identity.foundation/jwt-vc-presentation-profile/#normative-references) provides interoperability with any app that complies with DIF JWT-VC Profile.
The service can also use PingOne native protocols. The PingOne native protocol only works with apps that use the [PingOne Neo Native SDKs](../native-sdks/pingone-neo-native-sdks.html), which has more features but is restricted to only supported apps.
## Assigning admin roles and permissions to this service
Admin role assignments determine access to PingOne APIs. When assigning admin roles to this service, refer to [PingOne Permissions by Service](../platform/reference/roles-and-permissions-in-pingone/permissions-by-service.html) for the service-specific permissions.
You can also choose to assign admin roles based on particular service resources. Refer to [PingOne Permissions by Resource](../platform/reference/roles-and-permissions-in-pingone/permissions-by-resource.html) when assigning admin roles per service resources.
Admin assignments to roles are set by:
* [Automatic assignment for some roles](../platform/roles/predefined-roles.html#automatic-role-assignment).
* [Group Role Assignments](../platform/group-role-assignments/group-role-assignments.html).
* [User Role Assignments](../platform/users/user-role-assignments.html).
Refer to [Roles Management](../platform/roles.html) for more information.
## Credential Verifications session data model
| Property | Type | Required? | Mutable? | Description |
| --------------------------------- | --------- | ----------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `_links.appOpenURL.href` | String | N/A | Read-only | URL to use in a mobile browser to open a compatible wallet app, such as the PingOne Neo Sample App. |
| `_links.qr.href` | String | N/A | Read-only | URL to return a QR code that, when evaluated, opens the compatible wallet app to this verification. |
| `_links.self.href` | String | N/A | Read-only | URL to return this same response. |
| `applicationInstance.id` | String | Required/Optional | Immutable | Identifier (UUID) of the application running the Wallet SDK on the user's device and registered with the service. When set and `protocol` is `NATIVE`, the service sends a push notification to the application instance using the settings of the digital wallet application. |
| `createdAt` | DateTime | N/A | Read-only | Date and time the credential verifications session was created. |
| `didMethod` | String | Optional | Immutable | The decentralized identifier method to use during the credential verification session. Can be `JWK`, the default, or `ION`. |
| `digitalWalletApplication.id` | String | Optional | Immutable | Identifier (UUID) of the customer's digital wallet app that interacts with the user's digital wallet. When set and `protocol` is `NATIVE`, the service uses the `appOpenURL` defined on the [Digital Wallet App](digital-wallet-apps.html) instead of `shocard.pingone.com`. |
| `errors` | Object\[] | N/A | Read-only | Array of objects representing errors recorded when attempting an action on a credential. Refer to [Credential Verifications errors object data model](#credential-verifications-error-object-data-model). |
| `expiresAt` | DateTime | N/A | Read-only | Date and time the credential verifications session will expire. |
| `id` | String | N/A | Read-only | Identifier (UUID) of the credential verification session. |
| `issuerFilter.dids` | String\[] | Optional | Immutable | Array of unique [Decentralized Identifiers (DID)](https://www.w3.org/TR/did-core/). Ignored if `protocol` is `NATIVE`. Refer to the note following this table. |
| `issuerFilter.environmentIds` | String\[] | Optional | Immutable | Array of PingOne environment identifiers. Refer to the note following this table. |
| `message` | String | Optional | Immutable | A message shown to the user by the compatible wallet app to alert the user. |
| `notification` | Object | Optional | Immutable | Contains notification information. When `protocol` is `NATIVE` and `applicationInstance.id` is set, permits administrators to customize their push notification. |
| `notification.template` | Object | Optional | Immutable | Contains template parameters. |
| `notification.template.locale` | String | Optional | Immutable | The ISO 2-character language code used for the notification; for example, `en`. |
| `notification.template.variables` | Object\[] | Required/Optional | Immutable | An object of name-value pairs that defines the dynamic variables used by the content variant. Required if the template requires variables, otherwise ignored. For more information on dynamic variables, refer to [Dynamic variables](../platform/notifications/notifications-templates.html#notifications-templates-dynamic-variables). |
| `notification.template.variant` | String | Optional | Immutable | The unique user-defined name for the content variant that contains the message text used for the notification. For more information on variants, refer to [Creating custom contents](../platform/notifications/notifications-templates.html#notifications-templates-creating-custom-contents). |
| `protocol` | String | Optional | Immutable | Protocol to use for verification; can be `OPENID4VP` or `NATIVE`. If not present, defaults to `NATIVE`. |
| `protocolVersion` | String | Optional | Immutable | Protocol version. Only applicable to `OPENID4VP`. If not present, defaults to `JWT-VC-Presentation-Profile-v0.0.1`. |
| `requestedCredentials` | Object\[] | Required | Immutable | Array of objects that contain the type of credentials to verify and the keys to return from the credential. Refer to the important note following this table. |
| `requestedCredentials.keys` | String\[] | Optional | Immutable | Array of strings that identify the key names for selective disclosure to return from the credential. |
| `requestedCredentials.type` | String | Required | Immutable | Type of credential to verify. Must be the name of a PingOne credential type issued by the credential issuer. |
| `status` | String | N/A | Read-only | Status of the verification request; can be `INITIAL`, `WAITING`, `EXPIRED` (verification session expired),`VERIFICATION_SUCCESSFUL`, or `VERIFICATION_FAILED`. |
| `timeoutSeconds` | Integer | Optional | Immutable | Maximum number of seconds the presentation session is active. Must be in the range of 30 to 600 seconds. Default is 300 seconds. |
The service uses `timeoutSeconds` to determine the `expiresAt` timestamp during presentation session creation. The user must receive the push notification or scan the QR code and then share the requested credential before this time. The service returns `status` of `EXPIRED` if the user attempts to share a credential after the `expiresAt` time. The service also returns `status` of `EXPIRED` if the user does not share a credential before the `expiresAt` time.
The digital wallet service uses the `credential_verification` notification template to send a push notification to a digital wallet when a [Create Credential Verification Session (NATIVE - Push Notification)](credential-verifications/create-credential-verification-presentation-session-native-push-notification.html) is created. The `notification.template` object can define a variant and locale for the notification, if needed.
| | |
| - | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| | Content of `requestedCredentials` differs by `protocol`:- The `protocol` of `OPENID4VP` permits only one credential type per request and ignores `requestedCredentials.keys` if present.
- The `protocol` of `NATIVE` permits multiple credential types per request and uses `requestedCredentials.keys` to return only those selected data fields for each credential type. |
If `issuerFilter.environmentIds` is submitted, the service searches all listed environments for the issuer of the presented credential. If the user presents a credential that is not from one of these issuers, the verification fails with `status` of `VERIFICATION_FAILED`.
If `issuerFilter.dids` is submitted and `protocol` is `OPENID4VP`, the service searches all listed decentralized identifiers (DID) for the issuer of the presented credential. If the user presents a credential that is not from one of these issuers, the verification fails with `status` of `VERIFICATION_FAILED`.
This `issuerFilter.dids` typically contains decentralized identifiers for issuers that are not using PingOne Credentials for JWT-VC issuance. The service supports these three DID methods:
* did:web - ; used for the issuer and verifier
* did:jwk - ; used for the holder or subject
* did:ion - (The service supports only [long-form URIs](https://identity.foundation/sidetree/spec/#long-form-did-uris) for this method)
## Credential Verifications credential data data model
| Property | Type | Required? | Mutable? | Description |
| --------------------------- | --------- | --------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `_links.self.href` | String | N/A | Read-only | URL to return this verification credential data. |
| `credentialData` | Object\[] | N/A | Read-only | Array of objects containing the data found on the credential. |
| `credentialData.data` | Object\[] | N/A | Read-only | Array of objects containing the name-value pairs found on the credential. If a credential has not yet been shared, `status` is `INITIAL` or `WAITING`, then returns as an empty array. |
| `credentialData.data.key` | String | N/A | Read-only | Name of the key of a name-value pair found on the credential. |
| `credentialData.data.value` | String | N/A | Read-only | Value of a name-value pair found on the credential. |
| `credentialData.issuerId` | String | N/A | Read-only | Identifier (UUID) of the issuer of the credential verified in the format from the credential issuer. |
| `credentialData.issuerLogo` | String | N/A | Read-only | Base64-encoded logo of the issuer of the credential. |
| `credentialData.issuerName` | String | N/A | Read-only | Name of the issuer of the credential verified. |
| `credentialData.type` | String | N/A | Read-only | Space-delimited list of the types of credential verified. |
| `credentialData.types` | String\[] | N/A | Read-only | Array of the types of credential verified. |
| `errors` | Object\[] | N/A | Read-only | Array of objects representing errors recorded when attempting an action on a credential. Refer to [Credential Verifications errors object data model](#credential-verifications-error-object-data-model). |
| `id` | String | N/A | Read-only | Identifier (UUID) of the verification credential data. |
| `status` | String | N/A | Read-only | Status of the verification request; can be `INITIAL`, `WAITING`, `EXPIRED` (verification session expired), `VERIFICATION_SUCCESSFUL`, or `VERIFICATION_FAILED`. |
## Credential Verifications session data data model
| Property | Type | Required? | Mutable? | Description |
| ------------------------------------------ | --------- | --------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `_links.appOpenURL.href` | String | N/A | Read-only | URL to use in a mobile browser to open a compatible wallet app, such as the PingOne Neo Sample App. |
| `_links.qr.href` | String | N/A | Read-only | URL to return a QR code that, when evaluated, opens the compatible wallet app to this verification. |
| `_links.self.href` | String | N/A | Read-only | URL to return this verification session data. |
| `applicationInstance.id` | String | N/A | Read-only | Identifier (UUID) of the application running the Wallet SDK on the user's device and registered with the service. |
| `errors` | Object\[] | N/A | Read-only | Array of objects representing errors recorded when attempting an action on a credential. Refer to [Credential Verifications errors object data model](#credential-verifications-error-object-data-model). |
| `id` | String | N/A | Read-only | Identifier (UUID) of the verification session data. |
| `status` | String | N/A | Read-only | Status of the verification request; can be `INITIAL`, `WAITING`, `EXPIRED` (verification session expired), `VERIFICATION_SUCCESSFUL`, or `VERIFICATION_FAILED`. |
| `verifiedData` | Object\[] | N/A | Read-only | Array of objects containing the data found on the credential. |
| `verifiedData.data` | Object | N/A | Read-only | Object containing the name-value pairs found on the credential. If a credential has not yet been shared, `status` is `INITIAL` or `WAITING`, then returns as an empty array. |
| `verifiedData.data.key` | String | N/A | Read-only | Name of the key of a name-value pair found on the credential. |
| `verifiedData.data.value` | String | N/A | Read-only | Value of a name-value pair found on the credential. |
| `verifiedData.metaData` | Object | N/A | Read-only | Contains metadata associated with the credential. |
| `verifiedData.metaData.issuanceDate` | String | N/A | Read-only | The date and time the credential was issued in ISO 8601 YYYY-MM-DDTHH:MM:SS.sssZ format (milliseconds optional). |
| `verifiedData.metaData.issuerId` | String | N/A | Read-only | Identifier (UUID) of the issuer of the credential verified in the format from the credential issuer. |
| `verifiedData.metaData.issuerLogo` | String | N/A | Read-only | Base64-encoded logo of the issuer of the credential. |
| `verifiedData.metaData.issuerName` | String | N/A | Read-only | Name of the issuer of the credential verified. |
| `verifiedData.metaData.verificationStatus` | String | N/A | Read-only | Verification status of the credential. Can be `VALID` or `INVALID`. |
| `verifiedData.type` | String | N/A | Read-only | Space-delimited list of the types of credential verified. |
| `verifiedData.types` | String\[] | N/A | Read-only | Array of the types of credential verified. |
### Credential Verifications errors object data model
| Property | Type | Required? | Mutable? | Description |
| ---------------- | ------ | --------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `errors.code` | String | N/A | Read-only | A code that indicates the error encountered by the service. Refer to [Credential Verifications error codes](#credential-verifications-error-codes). |
| `errors.target` | String | N/A | Read-only | The part of the credential that caused the error encountered by the service. |
| `errors.message` | String | N/A | Read-only | A message that describes the error encountered by the service. |
## Credential Verifications error codes
| Code | Message |
| ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| REQUESTED\_CREDENTIAL\_MISSING | One or more of the requested credential types is not included in the presentation from the user. |
| REQUESTED\_FIELD\_MISSING | One or more of the requested fields for one or more credential types is not included in the presentation from the user. |
| INVALID\_TOKEN | The `idToken` presented by the user's wallet is not valid (format or signature error). |
| INVALID\_CREDENTIAL | One or more of the credentials presented by the user could not be validated. Many different errors can cause this. A more specific error is returned in the errors array of the [Read Credential Verification Credential Data](credential-verifications/read-credential-verification-credential-data.html) or [Read Credential Verification Session Data](credential-verifications/read-credential-verification-session-data.html) response. |
| UNEXPECTED\_ERROR | An unexpected error occurred during credential verification. |
## Response codes
| Code | Message |
| ---- | --------------------------------------------------------------------- |
| 200 | Successful operation. |
| 400 | The request could not be completed. |
| 401 | You do not have access to this resource. |
| 403 | You do not have permissions or are not licensed to make this request. |
| 404 | The requested resource was not found. |
| 500 | Unexpected server error. |