PingOne Platform APIs

User Credentials

Use the User Credentials service to create a user credential and get the credential status. To issue the credential to the user you must first create a credential type (automated) or create a credential type (managed). After you create a credential type, you can issue credentials to users two ways depending on the management.mode of the credential type:

Regardless of management.mode, you can revoke a user credential, read all user credentials, read one user credential, or read one user credential wallets.

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.

User Credentials data model

Property Type Required Mutable Description

createdAt

DateTime

N/A

Read-only

Date and time the user credential was created.

credentialType.id

String

Required

Immutable

Identifier of the credential type.

data

Object

Optional

Mutable

Fields submitted for the credential.

data.<field>

String

Required/Optional

Mutable

Fields for user data. Refer to data object data model.

demoDataStorage

Object

Optional

Immutable

Object with flags related to storing credential data. Refer to demoDataStorage object data model.

demoDataStorage.storeUntilIssued

Boolean

Optional

Immutable

Whether or not the credential data should be stored until it is issued.

demoDataStorage.hasData

Boolean

N/A

Read-only

Whether or not the credential data is stored.

environment.id

String

N/A

Read-only

Identifier (UUID) of the environment associated with the user.

expiresAt

DateTime

Optional

Mutable

The date that the user credential expires. If this value is null, the credential never expires.

id

String

N/A

Read-only

Identifier (UUID) of the user credential.

notification

Object

Optional

Immutable

Contains notification information. When this property is supplied, the information within is used to create a custom notification.

notification.methods

String[]

Optional

Immutable

Array of methods for notifying the user. Can be EMAIL, SMS, or both.

notification.results

Object

N/A

Read-only

Contains the results of attempts to notify the user.

notification.results.
error

Object

N/A

Read-only

Contains information regarding why a notification failed to send.

notification.results.
method

String

N/A

Read-only

Method used in the attempt to notify the user. Can be EMAIL or SMS.

notification.results.
notification.id

String

N/A

Read-only

Identifier (UUID) of the notification that was sent.

notification.results.
sent

Boolean

N/A

Read-only

Whether the notification was successfully sent.

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

Required

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.

status

String

N/A

Read-only

Status of the user credential. Can be ISSUED, PENDING, REVOKED, or DELETED.

title

String

N/A

Read-only

Returned as defined in the credential type.

updatedAt

DateTime

N/A

Read-only

Date and time the credential type was last updated. Can be null.

user.id

String

Required

Immutable

Identifier (UUID) of the user. Supplied in the endpoint.

The one notification.template object applies a variant and locale to all three credential notification templates: credential_issued, credential_updated, and credential_revoked. When adding a variant or locale to any of the three notification templates, consider adding the same variant or locale to the other notification templates. If a requested variant is not defined, the notification uses the default notification template. If a requested locale is not defined, the notification uses the user’s preferred language or, if the user has no preferred language, the default language of the environment.

Although notification.template is immutable, Update a User Credential can change notification.template on a specific credential for its life span.

data object data model

The data object is only used in the request body and is ephemeral, it is used to create the credential and discarded. It is not returned with Read All User Credentials or Read One User Credential. This permits, for example, submission of sensitive information that customers do not want to store in a user directory.

Because the data is not stored, the user credential can only be provisioned to digital wallets that are already paired. If no paired digital wallets exist on the user when the user credential is created or updated, the credential is not issued and an error message is returned.

For non-production use, this rule has an exception as discussed in demoDataStorage object data model.

The data object can only be used for Credential Types where its management.mode is MANAGED. Individual fields in data can only be used where the corresponding credential type’s metadata.fields.type is Alphanumeric Text. If the corresponding credential type’s metadata.fields.value is valued, that value represents a default for the field and can be overridden in Create a User Credential or Update a User Credential API requests.

The data object contains any number of keys, where the key is the title in metadata.fields that represents a specific attribute of the credential type required by the issuer. For example, an insurance company might have a metadata.fields.title of Endorsements and the corresponding data key would be Endorsements. These data fields must match the metadata.fields defined for the credential type in credentialType.id. For more information on fields, refer to the fields object in metadata object data model and the data types in fields.type types.

Whether any given data.<field> is required or optional depends on the corresponding fields.required and fields.value in the metadata object of the credential type. A data.<field> is required when fields.required is true and no fields.value exists and optional when fields.required is false or when fields.value has a value.

demoDataStorage object data model

When you create a user credential for a managed credential type, the request body can provide values for fields in data that are not extracted from directory attributes. The service applies the provided data to the credential but never stores that data. This means that the user must already have a paired digital wallet that the new credential can be provisioned to. If the user pairs a digital wallet after the user credential was created, or if the user wants to use a OID4VCI wallet, they cannot receive the credential because the service no longer has the data.

When demoDataStorage.storeUntilIssued is true, the service stores data until used when issuing the credential. The data object is discarded after the credential is issued. This allows for testing of the user credentials API without permanently storing data, which is ideal for testing non-production environments or for testing OID4VCI credential issuance.

Until the credential is issued and discarded, data fields are visible using Read All User Credentials or Read One User Credential and can be updated using Update a User Credential.

Therefore, demoDataStorage should only be used for testing purposes in non-production environments. It is not recommended for production use.

Provisioned Credentials data model (credential)

This object is shared with digital wallets. It is returned only with Read One User Credential Wallets and Read One Digital Wallet Credentials. The former returns all digital wallets associated with the specified user credential, the latter returns all user credentials associated with the specified digital wallet.

Property Type Required Mutable Description

claimReference

Object

N/A

Read-only

The serialized JSON object used to create the ClaimReference object returned. This is needed to revoke an issued credential.

createdAt

DateTime

N/A

Read-only

Date and time the credential was provisioned.

credential.id

String

N/A

Read-only

Identifier (UUID) of the user credential associated with the provisioned credential.

digitalWallet.id

String

N/A

Read-only

Identifier (UUID) of the digital wallet associated with the provisioned credential.

formats

String[]

N/A

Read-only

Array of protocols used to retrieve the provisioned credential. Can be NATIVE, jwt_vc_json, or dc+sd-jwt.

environment.id

String

N/A

Read-only

Identifier (UUID) of the environment associated with the provisioned credential.

expiresAt

Date

N/A

Read-only

The date that the provisioned credential expires. If this value is null, the provisioned credential never expires.

formats

String[]

N/A

Read-only

Array of protocols used to retrieve the provisioned credential. Can be NATIVE, jwt_vc_json, or dc+sd-jwt.

id

String

N/A

Read-only

Identifier (UUID) of the provisioned credential.

openid4VciWallet

Object

N/A

Read-only

Information about the wallet that used OpenID4VCI.

openid4VciWallet.client_id

String

N/A

Read-only

Client identifier provided by the wallet that used OpenID4VCI.

openid4VciWallet.walletDid

String

N/A

Read-only

Decentralized identifier (DID) provided in the proof JWT during OpenID4VCI issuance used to identify the wallet instance.

protocol

String

N/A

Read-only

Protocol used to retrieve the provisioned credential. Can be NATIVE or OPENID4VCI.

status

String

N/A

Read-only

Status of the provisioned credential. Can be CREATED, ACCEPTED, REJECTED, REVOKED, or DELETED.

user.id

String

N/A

Read-only

Identifier (UUID) of the user associated with the provisioned credential.

walletActions

Object[]

N/A

Read-only

Array of actions taken regarding the provisioned credential.

walletActions.action

String

N/A

Read-only

Action taken regarding the provisioned credential. Can be CREDENTIAL_ACCEPTED, CREDENTIAL_REJECTED, CREDENTIAL_REVOKED, or CREDENTIAL_DELETED.

walletActions.occurredAt

DateTime

N/A

Read-only

Date and time that the action occurred.

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.