PingOne Platform APIs

OpenID for Verifiable Credential Issuance Offers

The credentials service supports the OpenID for Verifiable Credential Issuance (OpenID4VCI) standard. By adhering to standards, Ping delivers the following values:

  • Interoperability: Enables seamless credential issuance across different identity wallets and verification platforms that support OpenID4VCI.

  • Enhanced Privacy: Minimizes unnecessary exposure of user data by allowing for selective disclosure via SD-JWT.

  • Regulatory Compliance: Aligns with OAuth 2.0, OpenID Connect, and W3C Verifiable Credential standards, supporting GDPR and other privacy regulations.

To use OpenID4VCI to issue a credential to a user, two conditions must be met:

  1. You must create a verifiable credential for the user either with an issuance rule, for credential types with management.mode of AUTOMATIC, or directly creating a user credential, for credential types with management.mode of MANAGED. The credential remains queued until retrieved by the user.

  2. You must create a workflow that notifies the user of the credential and that enables the user to retrieve the credential offer. For example, the workflow can be a DaVinci flow or a web app that interacts with the user. Your use case determines how your user interacts with your issuance application.

After those conditions are met, your workflow has your PingOne Worker App call Initiate OpenID4VCI Offers that returns the OpenID4VCI offer details. That credential offer is valid for 30 minutes. The user’s wallet must call the credentialOfferUrl.href endpoint to initiate the OpenID4VCI flow. Your workflow must induce the user’s wallet to start the OpenID4VCI flow, and the credential offer includes two methods:

  • qrCode.href: A base64 encoded PNG image of a QR Code that contains the openid-credential-offer URL. This can be embedded in a web view and shown to a user to be scanned by their mobile phone, which will open the wallet app and start the OpenID4VCI flow.

  • openid-credential-offer.href: A link with an openid-credential-offer scheme that a wallet will understand. If that link is read by the phone, clicked in an email or text message, or a page in the mobile browser, it will open the wallet app and start the OpenID4VCI flow.

When the wallet app follows that link, it communicates directly with the credential service to transfer the credential using the OpenID4VCI protocol. The wallet first requests the credential issuer metadata and then requests the credentials offered and available authentication methods. At this point, the OpenID4VCI protocol requires that the wallet (the user) authenticate with the credential issuer. How the user authenticates depends on the credential issuer’s configuration and how you choose to implement it.

The OpenID4VCI protocol supports two authentication methods: authorization_code and urn:ietf:params:oauth:grant-type:pre-authorized_code:

  • The authorization_code method requires the user to authenticate with the credential issuer, typically by entering their username and password. If the user initiates your workflow on their desktop, they might authenticate to the workflow to begin. When the workflow later transfers control to the wallet, the wallet must also authenticate because it is a different device. Repeating authentication is not an ideal user experience.

  • The pre-authorized_code method does not require the user to authenticate again with the credential issuer. The user authenticates to begin your workflow. However, when the user transfers control to the wallet, the credential issuer provides a pre-authorized code to the wallet, which the wallet can use to request the credentials without requiring the wallet to authenticate again.

After the wallet authenticates, the wallet and the credentials service continue with the OID4VCI protocol to deliver the queued credentials requested by the user to the wallet.

Use of NATIVE protocol and OID4VCI protocol are not mutually exclusive. If a user has a wallet with the PingOne Wallet SDK that uses NATIVE and another wallet that uses OID4VCI, you can issue a credential to both wallets using their respective protocols.

OpenID4VCI Credentials Issuance Offers data model

Property Type Required? Mutable? Description

_links.credentialOfferUrl.href

String

N/A

Read-only

The same URL from the response body credentialOfferUrl.

_links.environment.href

String

N/A

Read-only

URL to retrieve more information about the environment for this credential offer.

_links.openid-credential-offer.href

String

N/A

Read-only

Credential offer URL using the openid-credential-offer URI scheme defined in the standard. This can be used to trigger the mobile OS opening a Wallet app that supports this scheme.

_links.qrCode.href

String

N/A

Read-only

A base64 encoded PNG image of a QR Code that contains the openid-credential-offer URL. This can be embedded in a web view and shown to a user to be scanned by their mobile phone.

_links.self.href

String

N/A

Read-only

URL to return this same response.

_links.user.href

String

N/A

Read-only

URL to retrieve information about the user associated with this credential offer.

createdAt

String

Required

Immutable

The timestamp indicating when the credential offer was created.

grantTypes

String[]

Optional

Mutable

Array of strings that indicate allowable code grant types for this credential issuance. Can be authorization_code, the default, or urn:ietf:params:oauth:grant-type:pre-authorized_code.

credentials

String[]

Optional

Mutable

Indicates the list of credentials to be issued. If not provided, all credentials for the user will be provisioned.

credentialOfferUrl

String

Required

Immutable

URL to show or send to the wallet to start the OpenID4VCI flow in the wallet. This URL will use the environment’s custom domain if one is configured.

environment.id

String

N/A

Read-only

Identifier (UUID) of the environment this credential offer belongs to. A credential offer is valid for 30 minutes.

expiresAt

String

Required

Immutable

The timestamp indicating when the credential offer expires. Credential offer is valid for 30 minutes.

id

String

Required

Immutable

The unique identifier (UUID) for the credential offer.

requiredScopes

String[]

Optional

Mutable

Indicates the list of OAuth 2.0 scopes required for the credential issuance. The wallet must receive and use an access token that contains these scopes when requesting the credentials.

status

String

Required

Immutable

The current status of the credential offer. Can be CREATED, the credential offer has been created but the user has not received any credentials yet; ISSUING, the credential offer is for multiple different credential types and at least one credential but not all credentials have been provisioned; or COMPLETED: the credential offer has been fully provisioned.

user.id

String

N/A

Read-only

Identifier (UUID) of the user associated with this credential offer.