PingOne Platform APIs

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 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, which has more features but is restricted to only supported apps.

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.

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

id

String

N/A

Read-only

Identifier (UUID) of the credential verification session.

issuerFilter.dids

String[]

Optional

Immutable

Array of unique Decentralized Identifiers (DID). 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.

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.

protocol

String

Optional

Immutable

Protocol to use for verification; can be OPENID4VP or NATIVE. If not present, defaults to NATIVE.

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, VERIFICATION_SUCCESSFUL, VERIFICATION_FAILED, or VERIFICATION_EXPIRED.

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) 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:

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.

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, VERIFICATION_SUCCESSFUL, VERIFICATION_FAILED, or VERIFICATION_EXPIRED.

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.

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, VERIFICATION_SUCCESSFUL, VERIFICATION_FAILED, or VERIFICATION_EXPIRED.

verifiedData

Object[]

N/A

Read-only

Array of objects containing the data found on the credential.

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

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.

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 or Read Credential Verification Session Data 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.