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.

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.

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.

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.

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 Medical Limitations and the corresponding data key would be Medical Limitations. 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.

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.

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.

id

String

N/A

Read-only

Identifier (UUID) of the provisioned credential.

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.