PingOne Platform APIs

Credential Verifications

The Credential Verification service receives, and responds to, requests for credential verification using Decentralized Identity Foundation JSON 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.

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 for the service-specific permissions.

You can also choose to assign admin roles based on particular service resources. Refer to PingOne Permissions by Resource when assigning admin roles per service resources.

Admin assignments to roles are set by:

Refer to Roles Management 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 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.

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). 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 for English.

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.

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

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.

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.

Credential Verifications errors

In addition to the general error codes, credential verification operations can return the following errors:

HTTP status Top‑level code Detail code When it happens and what the response contains

400

INVALID_DATA

EMPTY_VALUE or INVALID_VALUE

Message: Validation Error : [<property> <message>]

When and details

When: A POST /presentationSessions request omits both requestedCredentials and schemaSets, supplies a requestedCredentials.type that is null or an empty string, supplies a timeoutSeconds outside the range of 30 to 600 seconds, or supplies a digitalWalletApplication or applicationInstance relationship without an id

Details: The Bean-Validation literal for the failing property, for example either requestedCredentials or schemaSets must be provided when both are omitted, Requested credential type cannot be null or a zero length trimmed string for a blank type, Timeout must be greater than or equal to 30 seconds or Timeout must be less than or equal to 600 seconds for an out-of-range timeoutSeconds, or must have an id for a relationship without an id (for example Validation Error : [timeoutSeconds Timeout must be less than or equal to 600 seconds])

400

INVALID_DATA

INVALID_VALUE

Message: The request could not be completed. One or more validation errors were in the request.

When and details

When: A POST /presentationSessions request references an applicationInstance.id that is not registered with id-routing, or a digitalWalletApplication.id that does not exist for the issuer

Details: applicationInstance does not exist for the applicationInstance relationship, or digitalWalletApplication could not be found for the digitalWalletApplication relationship

400

INVALID_DATA

INVALID_VALUE

Message: The request could not be completed. One or more validation errors were in the request.

When and details

When: A POST /presentationSessions request supplies an issuerFilter.dids value that does not begin with did:web:, did:ion:, or did:jwk:, or supplies an issuerFilter.environmentIds value that does not have a recognized PingOne credential issuer profile

Details: Unrecognized did method in issuerFilter <did> or EnvironmentId <environmentId> not a recognized PingOne Issuer

400

INVALID_REQUEST

INVALID_VALUE

Message: The request could not be completed. The request was malformed or invalid.

When and details

When: A path identifier cannot be parsed as a UUID, or the request body cannot be deserialized as JSON

Details: For a JSON field conversion error, the target is the field path and the detail message is Invalid value for attribute.. Otherwise no detail is returned

403

ACCESS_FAILED

INSUFFICIENT_PERMISSIONS

Message: The request could not be completed. You do not have access to this resource.

When and details

When: A POST /presentationSessions request with protocol of OPENID4VP supplies schemaSets or sets authRequestRequired to true with a token that is not platform-scoped

Details: schemaSets or authRequestRequired can only be used with platform-scoped tokens

403

ACCESS_FAILED

None

Message: The actor attempting to perform the request is not authorized.

When and details

When: The actor lacks the credentialsVerification:create:presentationSession permission (POST), the credentialsVerification:delete:presentationSession permission (DELETE), or the credentialsVerification:read:presentationSession permission (GET status, credential data, and session data)

Details: None

404

NOT_FOUND

None

Message: The request could not be completed. The requested resource was not found.

When and details

When: A GET or DELETE /presentationSessions/{credentialVerificationID} request references a credential verification session that is no longer in the session store (an expired session is still returned with its status of EXPIRED until its one-hour storage TTL evicts it), or a status, credential data, or session data request references a session that belongs to a different environment

Details: None

500

UNEXPECTED_ERROR

None

Message: There was an unexpected error with the service. Please try again later.

When and details

When: The service encounters an internal error while creating or processing the verification session.

Details: None