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.

User Credentials errors

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

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

400

INVALID_DATA

REQUIRED_VALUE

Message: The request is missing a required value.

When and details

When: A POST /credentials request omits the required credentialType.id property

Details: must not be null, reported against the credentialType 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 or PUT /credentials request references a credentialType.id that does not exist in the environment or was deleted

Details: credentialType could not be found, reported against the credentialType 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 or PUT /credentials request supplies a data key that does not match a field in the credential type’s metadata.fields or whose type does not accept client-provided data

Details: the following fields can not be provided by API client: <comma-separated field titles>, reported against the data property

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 PUT /credentials request supplies expiresAt for a user credential that already has an expiresAt value

Details: credential is already revoked, reported against the expiresAt property

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 or PUT /credentials request is made before a credential issuer profile exists for the environment

Details: issuerProfile must exist before creating Credentials

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

400

REQUEST_FAILED

CONSTRAINT_VIOLATION

Message: The request could not be completed. There was an issue processing the request.

When and details

When: A POST or PUT /credentials request issues a credential when the user has no paired digital wallet and the request does not enable demoDataStorage.storeUntilIssued (reported against the digitalWallets property), the credential type does not allow API issuance, a platform-scoped condition is violated (System provided user credential types can only be created PingOne Services or Data callback can only be used by PingOne Services), or a PUT targets a credential that is revoked or expired or was issued by an issuance rule or by a system-provided credential type, or changes demoDataStorage.storeUntilIssued after creation (reported against the demoDataStorage.storeUntilIssued property)

Details: user must have a paired Digital Wallet before issuing a Credential, credentialType does not allow API issuance, System provided user credential types can only be created PingOne Services, Data callback can only be used by PingOne Services, credential is already revoked, can not update credential issued by Issuance Rule, can not update system provided credential, or demoDataStorage.storeUntilIssued cannot be changed after creation, respectively

400

INVALID_DATA

CREDENTIAL_TYPE_INVALID or REQUIRED_FIELD_MISSING

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

When and details

When: Credential data cannot be calculated during create or update, such as metadata.fields being empty or more than 5 fields having fileSupport of BASE64_STRING or INCLUDE_FILE (CREDENTIAL_TYPE_INVALID), or a required field having no value from the directory attribute or the request data object (REQUIRED_FIELD_MISSING)

Details: fields are empty or at most 5 fields with fileSupport INCLUDE_FILE or BASE64_STRING are allowed for the metadata.fields property, or required field(s) are missing with an innerError listing the missing requiredFields

403

ACCESS_FAILED

INSUFFICIENT_PERMISSIONS

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

When and details

When: The caller has the operation permission but lacks population-level or group-level access to the target user and is not an environment-level administrator (applies to all user credential operations, which are gated by the user access enforcer)

Details: Insufficient permissions to access this user resource

403

ACCESS_FAILED

None

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

When and details

When: The actor lacks the credentialsIssuance:create:credentials permission (POST), the credentialsIssuance:update:credentials permission (PUT or revoke), the credentialsIssuance:delete:credentials permission (DELETE), or the credentialsIssuance:read:credentials permission (GET)

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, PUT, POST (revoke), or DELETE /credentials/{userCredentialID} request references a user credential that does not exist for the user, or the target user does not exist in the directory (the user access enforcer and user lookup run before the operation)

Details: None. A POST or PUT that references a user not in the directory returns user could not be found as the top-level message instead

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 calculating or storing the credential, such as a data size limit or expiration evaluation failure.

Details: None