User Management API

The PingID user management API consists of operations for managing PingID users, their status and their paired devices:

  • The user's lifecycle can be managed via the AddUser, GetUserDetails, EditUser and DeleteUser operations. These allow an administrator to perform CRUD actions on a user in the PingID service.
  • The status of a user (whether they are active, bypassed or suspended) can be managed with the ActivateUser, ToggleUserBypass and SuspendUser operations.
  • Devices are managed via the GetActivationCode, GetPairingStatus, StartOfflinePairing and FinalizeOfflinePairing, PairYubiKey and UnpairDevice operations.

 

This will pair a users device (and PingID application) to the PingID service so that a user can be authenticated via the AuthenticateOnline operation. The following workflow can be used to pair a user and their device:

  1. The organization's administrator enters the new user name in the organization's internal user directory
  2. The client application calls the AddUser PingID API with an activateUser value of "false"
  3. The client application offers the user a choice of registration methods: either online registration via mobile device, or offline registration via SMS, email, voice or YubiKey device
  4. The user chooses the Online Pairing method
  5. The client application calls the GetActivationCode operation
  6. The client application displays the the activation code to the user, in either numeric or QR code format
  7. The client application starts polling the device pairing status by calling the GetPairingStatus operation periodically
  8. In the PingID mobile app, the user either scans the QR code or types in the numeric code and selects "Pair Device"
  9. Once the PingID mobile app has been paired, the call to GetPairingStatus will return SUCCESS and the pairing process is complete

Note: If it is known that the user will use the online pairing process before creating the user, the activateUser parameter can be set to "true" during the AddUser operation to receive the activation code in the response to the AddUser operation rather than make a second call to the GetActivationCode operation.

 

 

 

The offline pairing workflow pairs the user's PingID account to either an SMS, Email or Voice authentication method. The following workflow can be implemented to pair a users device

  1. The organization's administrator enters the new user name in the organization's internal user directory
  2. The client application calls the AddUser PingID API with an activateUser value of "false"
  3. The client application offers the user a choice of registration methods: either online registration via mobile device, or offline registration via SMS, email, voice or YubiKey device
  4. The user chooses the offline pairing method
  5. The client application prompts the user to enter a phone number or an email address
  6. The client application calls the StartOfflinePairing operation, passing the user's choice of SMS, email or voice message and contact details
  7. The PingID service sends an OTP via SMS, email or voice message, depending on the method selected previously
  8. The client application prompts the user to enter the OTP received by SMS, email or voice message
  9. The client application calls the FinalizeOfflinePairing PingID API, passing the OTP that the user entered to complete the pairing process

 

 

 

An organization can use YubiKey's to provide an offline authentication method. Once the user has selected YubiKey as their authentication method, the following steps must be implemented:

  1. The organization's administrator enters the new user name in the organization's internal user directory
  2. The client application calls the AddUser PingID API with an activateUser value of "false"
  3. The client application offers the user a choice of registration methods: either online registration via mobile device, or offline registration via SMS, email, voice or YubiKey device
  4. The user chooses the YubiKey pairing method
  5. The client application prompts the user to enter an OTP obtained from the YubiKey device
  6. The client application calls the PairYubiKey operation, passing the OTP that the user entered to complete the pairing process
 

 

 

When a user wants to pair a FIDO security key, the service provider initiates the authentication process with the WebAuthnStartPairing API, which returns parameter data required for public key credentials.
These parameters are used as an input for the call to the browser’s "navigator.credentials.create" function, which is the next step in the WebAuthn pairing flow.
The "navigator.credentials.create function" returns the public key credentials.
The WebAuthnFinishPairing API then uses the public key credentials and input parameters in its request body, and completes the FIDO security key pairing process. For further information, refer to Example : PingID FIDO security key.

 

The following table describes the different statuses a user entity might have throughout its life-cycle. A user’s status depends both on the PingID administrator’s actions and on whether the user has registered a mobile device with the system.

Status Description
ACTIVE The user can perform any operation within the user’s privileges. This means that the administrator created this user in the system, and the user completed the registration process and was paired with a device.
PENDING The user started the registration process but did not finish it. Therefore the user is not yet paired with a device.
NOT_ACTIVE

The user exists in the system, but was not activated yet. This might occur if the administrator first creates a list of users and activates them later.

- OR -

The user was activated and was sent an activation message and code, but the activation code has expired.

PENDING_ACTIVATION The user was activated but not paired with a device.
SUSPENDED The administrator suspended this user’s ability to be authenticated by PingID. This might happen, for instance, if the user can’t find the registered device and the administrator wants to protect against a possible theft and illegal access to the system.
PENDING_CHANGE_DEVICE The user’s device was deleted by the administrator and should be re-registered with a new activation code. This might happen, for instance, if the user is upgrading to a new device.

 

When the organization's application calls the GetActivationCode operation, a numeric activation code is returned. Either the user can enter the numeric code manually into the PingID mobile app, or the application can render a QR code, which the user can scan within the PingID mobile app (or any QR reader).

To create the QR code to display to the user, create a string "act_code=<activation_code>" where <activation_code> is the numeric code you received in the GetActivationCode response. Then Base64 encode this value and append to the QR redirect URL below, finally perform QR encoding on the completed URL. This URL will redirect the user to the PingID mobile app (if they are not already using it) and pair the mobile app using the activation code:

https://idpxnyl3m.pingidentity.com/pingid/QRRedirection?base64(act_code=<activation_code>)

Note: There are a number of open source QR code generation libraries available. This document does not endorse a specific library to perform the encoding.

 

Use CreateJob to run a job. You can check the job status using GetJobStatus. The status is returned in the jobToken parameter. A status value of "done" indicates that the job executed successfully and the client can continue the job workflow (for example, using GetOrganizationReport). If the status is "failure", contact an administrator for assistance. A status of "in_progress" indicates the client needs to continue polling the job status using GetJobStatus until the status is "done".

The administrator who manages the service provider's users will initiate an AddUser operation for each new user the administrator wants to create in the PingID service. The new user will still have to be paired with a mobile device before using PingID for authentication.

This is the AddUser URL:

https://idpxnyl3m.pingidentity.com/pingid/rest/4/adduser/do

 

Request Body Parameters

Example reqBody object in the API payload:

"reqHeader": { ... },
"reqBody": {
 "activateUser": false,
 "fName": "John",
 "lname": "Doe",
 "email": "jdoe@pingdevelopers.com",
 "username": "jdoe",
 "role": "REGULAR"
 "clientData": "Session data echoed back to the requestor"
}

The parameters included in the reqBody object are:

Parameter DataType Description
activateUser Boolean Whether to activate as well as add the user (true/false). If this value is set to true, an activation code for the user is sent in the response.
clientData String Optional. This value is returned unchanged in the API response. It can be used to save state and/or client context data for the application between API calls.
email String Optional. The user's email address.
fName String Optional. The user's first name.
lname String Optional. The user's last name.
role String One of:

ADMIN - A user with administrator privileges.
REGULAR - A user without administrator privileges.
username String The user's assigned user name. Must be unique in an organization. Up to 250 characters; can contain any characters, including blanks.

 

Response Body Parameters

Example response body:

{
 "userDetails": {
  "email": "jdoe@jdoe.com",
  "lname": "Doe",
  "userEnabled": false,
  "fname": "John",
  "userInBypass": false,
  "spList": [],
  "lastLogin": null,
  "bypassExpiration": null,
  "deviceDetails": null,
  "lastTransactions": [],
  "userName": "jdoe",
  "status": "NOT_ACTIVE"
 },
 "errorId": 200,
 "errorMsg": "",
 "uniqueMsgId":"webs_sOFLeIP0EOlR-BnOCN_DTLv1uMpivQRoFN68edsYi4Y",
 "clientData": "Session data echoed back to the requestor"
}

The parameters included in the responseBody object are:

Parameter DataType Description
errorId Int A numeric error code.
errorMsg String A textual description of the error, if there was one.
uniqueMsgId String A unique ID for the response message. This is logged and used to track the specific transaction for troubleshooting purposes.
clientData String The value sent in the request’s clientData field.
userDetails Object See details in the table below.

The userDetails parameters:

Parameter DataType Description
bypassExpiration
DateTime (epoch) The date and time when the user's enabled bypass mode will expire (in UNIX epoch format).
deviceDetails Object The details of the default device that is paired for the user. See the deviceDetails table below.
devicesDetails Array An array of deviceDetails objects containing the details of the all the devices that are paired for the user.
email String The user's email address.
fname String The user's first name.
lastLogin DateTime (epoch) The date and time of the user's last login to PingID (in UNIX epoch format).
lastTransactions Array A list containing an object describing the user's most recent PingID transactions. See the lastTransactions table below.
lname String The user's last name. 
spList Array The list of objects describing the authentication services the user can access. The objects can be for these services: "web", "pingone" (indicates single sign-on), "ssh", "vpn". See the table below.
status String The user's status. One of:

ACTIVE - The user is paired with a device and can authenticate with PingID.
NOT_ACTIVE - The user was created in PingID but did not start the pairing process.
PENDING_ACTIVATION - The user was created and received a pairing key to register with the PingID app.
SUSPENDED - The user has been temporarily suspended and cannot authenticate using PingID.
PENDING_CHANGE_DEVICE - The user is registered but has been unpaired from a previously paired device.
userEnabled Boolean Indicates whether the user was enabled by the PingID account administrator. If so, the user can pair with a device and can then perform authentication.
userInBypass Boolean Indicates whether the user is in bypass mode.
userName String The user's PingID user name.

The deviceDetails list (one or more objects):

Parameters DataType Description
email String The user's email address for the OTP message (non-null if email authentication is configured).
appVersion String The PingID application version installed on the device.
hasWatch Boolean Indicates whether the authentication device is an Apple iWatch.
countryCode String The country code of the device's phone number (non-null if SMS or voice authentication is configured).
sentClaimedSms Int [Deprecated] The times within the current day that the user requested an OTP via SMS or voice message and used the OTP for authentication.
phoneNumber String The user's assigned phone number.
nickname String A nickname assigned to the user.
deviceModel String The manufacturer and model information for the device.
enrollment DateTime Format is: yyyy-MM-dd HH:mm:ss.SSS. U.S. MST timezone.
availableNotClaimedSms Int The times within the current day that the user requested an OTP via SMS or voice message and used the OTP for authentication.
availableClaimedSms Int The remaining available times within the current day that the user can request an OTP via SMS or voice message, which is then used for authentication. This value is reset daily (it is limited because of the costs incurred for the user).
deviceRole String The authenticating role of the device. This can be PRIMARY or SECONDARY.
pushEnabled Boolean Indicates whether the authentication process can push data to the device.
deviceId Long Uniquely identifies the device.
sentNotClaimedSms Int [Deprecated] The times within the current day that the user requested an OTP via SMS or voice message without using the OTP for authentication).
type String The type of device used (such as, Android or Yubikey).
osVersion String If applicable, the operating system version used by the device.

The lastTransactions list (an object):

Parameter DataType Description
type String The type of PingID transaction (such as, Swipe).
date DateTime (epoch) The date and time of the transaction (in UNIX epoch format).
details String A description of the transaction.

The spList list (an object):

Parameter DataType Description
spAlias String The alias used to identify the authentication service (such as, pingone or web).
status String The status of the authentication service. This can be either ACTIVE or NOT_ACTIVE.
bypassExpiration DateTime (epoch) The date and time bypass mode will expire for the user (in UNIX epoch format).
spName String The service name for the authentication service.

The service provider application may retrieve a user's details for display purposes, for instance, for displaying within a UI page in order to allow the user to edit the details.

This is the GetUserDetails URL:

https://idpxnyl3m.pingidentity.com/pingid/rest/4/getuserdetails/do

 

Request Body Parameters

Example reqBody object in the API payload:

"reqHeader": { ... },
"reqBody": {
 "getSameDeviceUsers": false,
 "userName": "jdoe",
 "clientData": "Session data echoed back to the requestor"
}

The parameters included in the reqBody object are:

Parameter DataType Description
getSameDeviceUsers
Boolean Whether to return multiple users paired with the same device.
userName String The name of the user whose details you want to retrieve.
clientData String Optional. This value is returned unchanged in the API response. It can be used to save state and/or client context data for the application between API calls.

 

Response Body Parameters

Example response body:

{
 "userDetails": {
 "email": "jdoe@gmail.com",
 "userName": "jdoe",
 "lname": "",
 "userInBypass": false,
 "spList": [],
 "lastLogin": null,
 "deviceDetails": null,
 "lastTransactions": [ {
  "details": null,
  "date": 1439904304000,
  "type": "CreateUser"
 } ],
 "userEnabled": false,
 "fname": "Johnny",
 "bypassExpiration": null,
 "status": "PENDING_ACTIVATION",
 "role": "ADMIN"
 },
 "sameDeviceUsersDetails": [],
 "errorId": 200,
 "errorMsg": "",
 "uniqueMsgId":"webs_sOFLeIP0EOlR-BnOCN_DTLv1uMpivQRoFN68edsYi4Y",
 "clientData": "Session data echoed back to the requestor"
}

The parameters included in the responseBody object are:

Parameter DataType Description
errorId Int A numeric error code.
errorMsg String A textual description of the error, if there was one.
uniqueMsgId String A unique ID for the response message. This is logged and used to track the specific transaction for troubleshooting purposes.
clientData String The value sent in the request’s clientData field.
sameDeviceUsersDetails
Array If requested, the user details for multiple users on the same device.
userDetails Object See details in the table below.

The userDetails parameters:

Parameter DataType Description
bypassExpiration
DateTime (epoch) The date and time when the user's enabled bypass mode will expire (in UNIX epoch format).
deviceDetails Object The details of the default device that is paired for the user. See the deviceDetails table below.
devicesDetails Array An array of deviceDetails objects containing the details of the all the devices that are paired for the user.
email String The user's email address.
fname String The user's first name.
lastLogin DateTime (epoch) The date and time of the user's last login to PingID (in UNIX epoch format).
lastTransactions Array A list containing an object describing the user's most recent PingID transactions. See the lastTransactions table below.
lname String The user's last name. 
spList Array The list of objects describing the authentication services the user can access. The objects can be for these services: "web", "pingone" (indicates single sign-on), "ssh", "vpn". See the table below.
status String The user's status. One of:

ACTIVE - The user is paired with a device and can authenticate with PingID.
NOT_ACTIVE - The user was created in PingID but did not start the pairing process.
PENDING_ACTIVATION - The user was created and received a pairing key to register with the PingID app.
SUSPENDED - The user has been temporarily suspended and cannot authenticate using PingID.
PENDING_CHANGE_DEVICE - The user is registered but has been unpaired from a previously paired device.
userEnabled Boolean Indicates whether the user was enabled by the PingID account administrator. If so, the user can pair with a device and can then perform authentication.
userInBypass Boolean Indicates whether the user is in bypass mode.
userName String The user's PingID user name.

The deviceDetails list (one or more objects):

Parameters DataType Description
email String The user's email address for the OTP message (non-null if email authentication is configured).
appVersion String The PingID application version installed on the device.
hasWatch Boolean Indicates whether the authentication device is an Apple iWatch.
countryCode String The country code of the device's phone number (non-null if SMS or voice authentication is configured).
sentClaimedSms Int [Deprecated] The times within the current day that the user requested an OTP via SMS or voice message and used the OTP for authentication.
phoneNumber String The user's assigned phone number.
nickname String A nickname assigned to the user.
deviceModel String The manufacturer and model information for the device.
enrollment DateTime Format is: yyyy-MM-dd HH:mm:ss.SSS. U.S. MST timezone.
availableNotClaimedSms Int The times within the current day that the user requested an OTP via SMS or voice message and used the OTP for authentication.
availableClaimedSms Int The remaining available times within the current day that the user can request an OTP via SMS or voice message, which is then used for authentication. This value is reset daily (it is limited because of the costs incurred for the user).
deviceRole String The authenticating role of the device. This can be PRIMARY or SECONDARY.
pushEnabled Boolean Indicates whether the authentication process can push data to the device.
deviceId Long Uniquely identifies the device.
sentNotClaimedSms Int [Deprecated] The times within the current day that the user requested an OTP via SMS or voice message without using the OTP for authentication).
type String The type of device used (such as, Android or Yubikey).
osVersion String If applicable, the operating system version used by the device.

The lastTransactions list (an object):

Parameter DataType Description
type String The type of PingID transaction (such as, Swipe).
date DateTime (epoch) The date and time of the transaction (in UNIX epoch format).
details String A description of the transaction.

The spList list (an object):

Parameter DataType Description
spAlias String The alias used to identify the authentication service (such as, pingone or web).
status String The status of the authentication service. This can be either ACTIVE or NOT_ACTIVE.
bypassExpiration DateTime (epoch) The date and time bypass mode will expire for the user (in UNIX epoch format).
spName String The service name for the authentication service.

The service provider application may allow users to edit their own details, such as first and last name or email address. The service provider's user administrator may also want to update user details. In both these cases, the service provider application calls EditUser.

This is the EditUser URL:

https://idpxnyl3m.pingidentity.com/pingid/rest/4/edituser/do

 

Request Body Parameters

Example reqBody object in the API payload:

"reqHeader": { ... },
"reqBody": {
 "activateUser": false,
 "email": "jdoe@pingdevelopers.com",
 "fName": "Johnny",
 "lName": "Doe",
 "role": "REGULAR"
 "userName": "jdoe",
 "clientData": "Session data echoed back to the requestor"
}

The parameters included in the reqBody object are:

Parameter DataType Description
activateUser Boolean Whether to activate as well as add the user (true/false). If this value is set to true, an activation code for the user is sent in the response.
email String Optional. The user's email address.
fName String
Optional. The user's first name.
lName String
Optional. The user's last name.
role String
One of:

ADMIN - A user with administrator privileges.
REGULAR - A user without administrator privileges.
username String
The user's username in the PingID system. Must be unique in an organization. Up to 250 characters; can contain any characters, including blanks.
clientData String
Optional. This value is returned unchanged in the API response. It can be used to save state and/or client context data for the application between API calls.

 

Response Body Parameters

Example response body:

{
 "userDetails": {
  "email": "jdoe@jdoe.com",
  "lname": "Doe",
  "userEnabled": false,
  "fname": "Johnny",
  "userInBypass": false,
  "spList": [],
  "lastLogin": null,
  "bypassExpiration": null,
  "deviceDetails": null,
  "lastTransactions": [],
  "userName": "jdoe",
  "status": "NOT_ACTIVE"
 },
 "errorId": 200,
 "errorMsg": "",
 "uniqueMsgId":"webs_sOFLeIP0EOlR-BnOCN_DTLv1uMpivQRoFN68edsYi4Y",
 "clientData": "Session data echoed back to the requestor"
}

The parameters included in the responseBody object are:

Parameter DataType Description
errorId Int A numeric error code.
errorMsg String
A textual description of the error, if there was one.
uniqueMsgId String A unique ID for the response message. This is logged and used to track the specific transaction for troubleshooting purposes.
clientData String
The value sent in the request’s clientData field.
activationCode String If the new user was activated during this call, an activation code is returned, which this user can use for online activation of their account.
userDetails Object An object that describes the user. See details in the table below.

The userDetails parameters:

Parameter DataType Description
bypassExpiration
DateTime (epoch) The date and time when the user's enabled bypass mode will expire (in UNIX epoch format).
deviceDetails Object The details of the default device that is paired for the user. See the deviceDetails table below.
devicesDetails Array An array of deviceDetails objects containing the details of the all the devices that are paired for the user.
email String The user's email address.
fname String The user's first name.
lastLogin DateTime (epoch) The date and time of the user's last login to PingID (in UNIX epoch format).
lastTransactions Array A list containing an object describing the user's most recent PingID transactions. See the lastTransactions table below.
lname String The user's last name. 
spList Array The list of objects describing the authentication services the user can access. The objects can be for these services: "web", "pingone" (indicates single sign-on), "ssh", "vpn". See the table below.
status String The user's status. One of:

ACTIVE - The user is paired with a device and can authenticate with PingID.
NOT_ACTIVE - The user was created in PingID but did not start the pairing process.
PENDING_ACTIVATION - The user was created and received a pairing key to register with the PingID app.
SUSPENDED - The user has been temporarily suspended and cannot authenticate using PingID.
PENDING_CHANGE_DEVICE - The user is registered but has been unpaired from a previously paired device.
userEnabled Boolean Indicates whether the user was enabled by the PingID account administrator. If so, the user can pair with a device and can then perform authentication.
userInBypass Boolean Indicates whether the user is in bypass mode.
userName String The user's PingID user name.

The deviceDetails list (one or more objects):

Parameters DataType Description
email String The user's email address for the OTP message (non-null if email authentication is configured).
appVersion String The PingID application version installed on the device.
hasWatch Boolean Indicates whether the authentication device is an Apple iWatch.
countryCode String The country code of the device's phone number (non-null if SMS or voice authentication is configured).
sentClaimedSms Int [Deprecated] The times within the current day that the user requested an OTP via SMS or voice message and used the OTP for authentication.
phoneNumber String The user's assigned phone number.
nickname String A nickname assigned to the user.
deviceModel String The manufacturer and model information for the device.
enrollment DateTime Format is: yyyy-MM-dd HH:mm:ss.SSS. U.S. MST timezone.
availableNotClaimedSms Int The times within the current day that the user requested an OTP via SMS or voice message and used the OTP for authentication.
availableClaimedSms Int The remaining available times within the current day that the user can request an OTP via SMS or voice message, which is then used for authentication. This value is reset daily (it is limited because of the costs incurred for the user).
deviceRole String The authenticating role of the device. This can be PRIMARY or SECONDARY.
pushEnabled Boolean Indicates whether the authentication process can push data to the device.
deviceId Long Uniquely identifies the device.
sentNotClaimedSms Int [Deprecated] The times within the current day that the user requested an OTP via SMS or voice message without using the OTP for authentication).
type String The type of device used (such as, Android or Yubikey).
osVersion String If applicable, the operating system version used by the device.

The lastTransactions list (an object):

Parameter DataType Description
type String The type of PingID transaction (such as, Swipe).
date DateTime (epoch) The date and time of the transaction (in UNIX epoch format).
details String A description of the transaction.

The spList list (an object):

Parameter DataType Description
spAlias String The alias used to identify the authentication service (such as, pingone or web).
status String The status of the authentication service. This can be either ACTIVE or NOT_ACTIVE.
bypassExpiration DateTime (epoch) The date and time bypass mode will expire for the user (in UNIX epoch format).
spName String The service name for the authentication service.

The service provider's administrator will initiate a DeleteUser request for a user who must be removed from the PingID authentication system, for instance an employee who leaves the company, or a customer who is no longer a user of the service provider.

This is the DeleteUser URL:

https://idpxnyl3m.pingidentity.com/pingid/rest/4/deleteuser/do

 

Request Body Parameters

Example reqBody object in the API payload:

"reqHeader": { ... },
"reqBody": {
 "userName": "jdoe",
 "clientData": "Session data echoed back to the requestor"
}

The parameters included in the reqBody object are:

Parameter DataType Description
username String The username of the user to delete.
clientData String Optional. This value is returned unchanged in the API response. It can be used to save state and/or client context data for the application between API calls.

 

Response Body Parameters

Example response body:

{
 "errorId": 200,
 "errorMsg": "",
 "uniqueMsgId":"webs_sOFLeIP0EOlR-BnOCN_DTLv1uMpivQRoFN68edsYi4Y",
 "clientData": "Session data echoed back to the requestor"
}

The parameters included in the responseBody object are:

Parameter DataType Description
errorId Int A numeric error code (200 indicates a successful operation)
errorMsg String A textual description of the error, if there was one.
uniqueMsgId String A unique ID for the response message. This is logged and used to track the specific transaction for troubleshooting purposes.
clientData String The value sent in the request’s clientData field.

 

The service provider's administrator may want to temporarily suspend a user from performing authentication via the PingID system, for example, if the user is on temporary leave. When a user is suspended, the user can't be authenticated and therefore can't access the service provider's services.

A suspended user can be reactivated by calling ActivateUser.

This is the SuspendUser URL:

https://idpxnyl3m.pingidentity.com/pingid/rest/4/suspenduser/do

 

Request Body Parameters

Example reqBody object in the API payload:

"reqHeader": { ... },
"reqBody": {
 "userName": "jdoe",
 "clientData": "Session data echoed back to the requestor"
}

The parameters included in the reqBody object are:

Parameter DataType Description
userName String The username of the user to suspend.
clientData String Optional. This value is returned unchanged in the API response. It can be used to save state and/or client context data for the application between API calls.

 

Response Body Parameters

Example response body:

{
 "errorId": 200,
 "errorMsg": "",
 "uniqueMsgId":"webs_sOFLeIP0EOlR-BnOCN_DTLv1uMpivQRoFN68edsYi4Y",
 "clientData": "Session data echoed back to the requestor"
}

The parameters included in the responseBody object are:

Parameter DataType Description
errorId Int A numeric error code (200 indicates a successful operation)
errorMsg String A textual description of the error, if there was one.
uniqueMsgId String A unique ID for the response message. This is logged and used to track the specific transaction for troubleshooting purposes.
clientData String The value sent in the request’s clientData field.

 

After a user has been suspended by calling SuspendUser, you can reactivate the user by calling ActivateUser.

This is the ActivateUser URL:

https://idpxnyl3m.pingidentity.com/pingid/rest/4/activateuser/do

 

Request Body Parameters

Example reqBody object in the API payload:

"reqHeader": { ... },
"reqBody": {
 "userName": "jdoe",
 "clientData": "Session data echoed back to the requestor"
}

The parameters included in the reqBody object are:

Parameter DataType Description
userName String The username of the user to activate.
clientData String Optional. This value is returned unchanged in the API response. It can be used to save state and/or client context data for the application between API calls.

 

Response Body Parameters

Example response body:

{
 "errorId": 200,
 "errorMsg": "",
 "uniqueMsgId":"webs_sOFLeIP0EOlR-BnOCN_DTLv1uMpivQRoFN68edsYi4Y",
 "clientData": "Session data echoed back to the requestor"
}

The parameters included in the responseBody object are:

Parameter DataType Description
errorId Int A numeric error code (200 indicates a successful operation)
errorMsg String A textual description of the error, if there was one.
uniqueMsgId String A unique ID for the response message. This is logged and used to track the specific transaction for troubleshooting purposes.
clientData String The value sent in the request’s clientData field.

 

The service provider's administrator may want to temporarily bypass authentication for a specific user. This could happen, for instance, if the user is having a temporary technical problem with a mobile device, and the user has spoken with the administrator and requested a bypass. When a user is in bypass mode, the user can login with a username and password alone, and is not prompted for PingID authentication.

Note: When you want to activate a bypass for the user, set the bypassUntil parameter value to a datetime that indicates the end of the bypass period. To remove the bypass for the user, call the same ToggleUserBypass operation, but set the bypassUntil value to null.

This is the ToggleUserBypass URL:

https://idpxnyl3m.pingidentity.com/pingid/rest/4/userbypass/do

 

Request Body Parameters

Example reqBody object in the API payload:

"reqHeader": { ... },
"reqBody": {
 "bypassUntil": 1439913346850,
 "userName": "jdoe",
 "clientData": "Session data echoed back to the requestor"
}

The parameters included in the reqBody object are:

Parameter DataType Description
bypassUntil DateTime (epoch) The end of the bypass period. This is a number which indicates the number of milliseconds between 1/1/1970 (Unix epoch in ms) and the desired end time in the UTC time zone.
userName String The username of the user to toggle user bypass.
clientData String Optional. This value is returned unchanged in the API response. It can be used to save state and/or client context data for the application between API calls.

 

Response Body Parameters

Example response body:

{
 "errorId": 200,
 "errorMsg": "",
 "uniqueMsgId":"webs_sOFLeIP0EOlR-BnOCN_DTLv1uMpivQRoFN68edsYi4Y",
 "clientData": "Session data echoed back to the requestor"
}

The parameters included in the responseBody object are:

Parameter DataType Description
errorId Int A numeric error code (200 indicates a successful operation)
errorMsg String A textual description of the error, if there was one.
uniqueMsgId String A unique ID for the response message. This is logged and used to track the specific transaction for troubleshooting purposes.
clientData String The value sent in the request’s clientData field.

 

The service provider's administrator may want to get an activation code for a user who has been added to the PingID system but not activated. The user then enteres this activation code either by typing it or scanning a QR code, to perform online activation.

This is the GetActivationCode URL:

https://idpxnyl3m.pingidentity.com/pingid/rest/4/getactivationcode/do

 

Request Body Parameters

Example reqBody object in the API payload:

"reqHeader": { ... },
"reqBody": {
 "userName": "jdoe",
 "clientData": "Session data echoed back to the requestor"
}

The parameters included in the reqBody object are:

Parameter DataType Description
username String The username of the user whose activation code you want.
clientData String Optional. This value is returned unchanged in the API response. It can be used to save state and/or client context data for the application between API calls.

 

Response Body Parameters

Example response body:

{
 "activationCode": "436348609435",
 "errorId": 200,
 "errorMsg": "",
 "uniqueMsgId":"webs_sOFLeIP0EOlR-BnOCN_DTLv1uMpivQRoFN68edsYi4Y",
 "clientData": "Session data echoed back to the requestor"
}

The parameters included in the responseBody object are:

Parameter DataType Description
activationCode Long The activation code for the user. 
errorId Int A numeric error code (200 indicates a successful operation)
errorMsg String A textual description of the error, if there was one.
uniqueMsgId String A unique ID for the response message. This is logged and used to track the specific transaction for troubleshooting purposes.
clientData String The value sent in the request’s clientData field.

 

The service provider's application can call GetPairingStatus to retrieve the pairing status of a specific user who has been prompted to perform online pairing. The pairing status retuend will vary depending on whether the pairing process hasn't started, is in progress, or has started, and whether the process was completed successfully.

This is the GetPairingStatus URL:

https://idpxnyl3m.pingidentity.com/pingid/rest/4/pairingstatus/do

 

Request Body Parameters

Example reqBody object in the API payload:

"reqHeader": { ... },
"reqBody": {
 "activationCode": "436348609435",
 "clientData": "Session data echoed back to the requestor"
}

The parameters included in the reqBody object are:

Parameter DataType Description
activationCode Long The activation code sent by PingID for device pairing.
clientData String Optional. This value is returned unchanged in the API response. It can be used to save state and/or client context data for the application between API calls.

 

Response Body Parameters

Example response body:

{
 "pairingStatus": "PAIRED",
 "errorId": 200,
 "errorMsg": "",
 "deviceId":2841591,
 "uniqueMsgId":"webs_sOFLeIP0EOlR-BnOCN_DTLv1uMpivQRoFN68edsYi4Y",
 "clientData": "Session data echoed back to the requestor"
}

The parameters included in the responseBody object are:

Parameter DataType Description
pairingStatus String The current status of the pairing operation. One of:

NOT_EXIST - No such valid activation code exists.
NOT_CLAIMED - No one used this activation code yet.
VERIFIED - The user has started the pairing process and successfully verified the activation code, but the pairing process is not complete.
PAIRED - Device pairing was conpleted, but user has not filled in the registration form.
SUCCESS - The user completed device pairing successfully. Note that this value is only returned the first time the status is queried after device pairing. Another query will produce a NOT_EXIST status.
errorId Int A numeric error code (200 indicates a successful operation)
errorMsg String A textual description of the error, if there was one.
uniqueMsgId String A unique ID for the response message. This is logged and used to track the specific transaction for troubleshooting purposes.
clientData String The value sent in the request’s clientData field.
deviceId Long The device ID that is associated with this device.

 

The call to StartOfflinePairing causes PingID to send an OTP to the user via email, SMS or voice message, as indicated in the call parameters. The user must then enter the OTP manually to the service provider's application, which should then call FinalizeOfflinePairing while providing the OTP, to complete the pairing process.

This is the StartOfflinePairing URL:

https://idpxnyl3m.pingidentity.com/pingid/rest/4/startofflinepairing/do

 

Request Body Parameters

Example reqBody object in the API payload:

"reqHeader": { ... },
"reqBody": {
 "username": "jdoe",
 "type": "SMS",
 "pairingData": "13035551234",
 "clientData": "Session data echoed back to the requestor",
 "validateUniqueDevice": "true"
}

The parameters included in the reqBody object are:

Parameter DataType Description
username String The username of the user to start offline pairing for.
type String The type of offline message to send to the user. One of:
SMS - to send a text message.
VOICE - to send a voice message.
EMAIL - to send an email message.
pairingData String The message target, whose value depends on the type value. Provide an international phone number for SMS and VOICE types, or an email address for the EMAIL type.
clientData String Optional.
This value is returned unchanged in the API response. It can be used to save state and/or client context data for the application between API calls.
validateUniqueDevice Boolean Optional.
Default: false.
Set to "true" in order to verify that the device is unique in the organization in context, as a prerequisite to pairing.

 

Response Body Parameters

Example response body:

{
 "sessionId": "oacts_rxodmgpbVkjVltIBVP7C7m6y6ddsOY-a8BYqpDHHxZY",
 "errorId": 200,
 "errorMsg": "",
 "uniqueMsgId":"webs_sOFLeIP0EOlR-BnOCN_DTLv1uMpivQRoFN68edsYi4Y",
 "clientData": "Session data echoed back to the requestor"
}

The parameters included in the responseBody object are:

Parameter DataType Description
sessionId String A session ID value that must be sent in the sessionId parameter of the matching FinalizeOfflinePairing call. 
errorId Int A numeric error code (200 indicates a successful operation)
errorMsg String A textual description of the error, if there was one.
uniqueMsgId String A unique ID for the response message. This is logged and used to track the specific transaction for troubleshooting purposes.
clientData String The value sent in the request’s clientData field.

 

The call to FinalizeOfflinePairing completes the pairing process initiated by calling StartOfflinePairing. The user enters the OTP manually to the service provider's application, which calls FinalizeOfflinePairing while providing this OTP value.

This is the FinalizeOfflinePairing URL:

https://idpxnyl3m.pingidentity.com/pingid/rest/4/finalizeofflinepairing/do

 

Request Body Parameters

Example reqBody object in the API payload:

"reqHeader": { ... },
"reqBody": {
 "sessionId": "oacts_rxodmgpbVkjVltIBVP7C7m6y6ddsOY-a8BYqpDHHxZY",
 "otp": "123456",
 "clientData": "Session data echoed back to the requestor"
}

The parameters included in the reqBody object are:

Parameter DataType Description
sessionId String The sessionId value received in the response to StartOfflinePairing.
otp String The one-time password entered by the user.
clientData String Optional. This value is returned unchanged in the API response. It can be used to save state and/or client context data for the application between API calls.

 

Response Body Parameters

Example response body:

{
 "errorId": 200,
 "errorMsg": "",
 "uniqueMsgId":"webs_sOFLeIP0EOlR-BnOCN_DTLv1uMpivQRoFN68edsYi4Y",
 "clientData": "Session data echoed back to the requestor"
}

The parameters included in the responseBody object are:

Parameter DataType Description
errorId Int A numeric error code (200 indicates a successful operation)
errorMsg String A textual description of the error, if there was one.
uniqueMsgId String A unique ID for the response message. This is logged and used to track the specific transaction for troubleshooting purposes.
clientData String The value sent in the request’s clientData field.

 

OfflinePairing pairs the user via email, SMS or voice message. There's no verification of the email or phone number supplied.

This is the OfflinePairing URL:

https://idpxnyl3m.pingidentity.com/pingid/rest/4/offlinepairing/do

 

Request Body Parameters

Example reqBody object in the API payload:

"reqHeader": { ... },
"reqBody": {
 "userName": "jdoe",
 "type": "SMS",
 "pairingData": "13035551234",
 "clientData": "Session data echoed back to the requestor",
 "validateUniqueDevice": "true"
}

The parameters included in the reqBody object are:

Parameter DataType Description
userName String The username of the user to suspend.
type String The type of offline message to send to the user. One of:
SMS - to send a text message.
VOICE - to send a voice message.
EMAIL - to send an email message.
pairingData String The message target, whose value depends on the type value. Provide an international phone number for SMS and VOICE types, or an email address for the EMAIL type.
clientData String Optional.
This value is returned unchanged in the API response. It can be used to save state and/or client context data for the application between API calls.
validateUniqueData Boolean Optional.
Default: false.
Set to "true" in order to verify that the device is unique in the organization in context, as a prerequisite to pairing.

 

Response Body Parameters

Example response body:

{
 "sessionId": "oacts_rxodmgpbVkjVltIBVP7C7m6y6ddsOY-a8BYqpDHHxZY",
 "errorId": 200,
 "errorMsg": "",
 "uniqueMsgId":"webs_sOFLeIP0EOlR-BnOCN_DTLv1uMpivQRoFN68edsYi4Y",
}

The parameters included in the responseBody object are:

Parameter DataType Description
sessionId String A session ID value that must be sent in the sessionId parameter of the StartOfflinePairing call. 
errorId Int A numeric error code (200 indicates a successful operation)
errorMsg String A textual description of the error, if there was one.
uniqueMsgId String A unique ID for the response message. This is logged and used to track the specific transaction for troubleshooting purposes.

 

The service provider application can call PairYubiKey to pair a user with a YubiKey device instead of a mobile device. In this case, the user enters an OTP that the YubiKey generates, and this value must be passed in the call parameters.

This is the PairYubiKey URL:

https://idpxnyl3m.pingidentity.com/pingid/rest/4/pairyubikey/do

 

Request Body Parameters

Example reqBody object in the API payload:

"reqHeader": { ... },
"reqBody": {
 "otp": "ccccccdugencbubvthvennvnduljtfhnjldtnctfdfkn",
 "username": "jdoe",
 "clientData": "Session data echoed back to the requestor",
 "validateUniqueDevice": "true"
}

The parameters included in the reqBody object are:

Parameter DataType Description
otp String A one-time password generated by the YubiKey.
username String The username of the user to pair with the YubiKey.
clientData String Optional.
This value is returned unchanged in the API response. It can be used to save state and/or client context data for the application between API calls.
validateUniqueDevice Boolean Optional.
Default: false.
Set to "true" in order to verify that the device is unique in the organization in context, as a prerequisite to pairing.

 

Response Body Parameters

Example response body:

{
 "errorId": 200,
 "errorMsg": "",
 "uniqueMsgId":"webs_sOFLeIP0EOlR-BnOCN_DTLv1uMpivQRoFN68edsYi4Y",
 "clientData": "Session data echoed back to the requestor"
}

The parameters included in the responseBody object are:

Parameter DataType Description
errorId Int A numeric error code (200 indicates a successful operation)
errorMsg String A textual description of the error, if there was one.
uniqueMsgId String A unique ID for the response message. This is logged and used to track the specific transaction for troubleshooting purposes.
clientData String The value sent in the request’s clientData field.

 

When a user activates a PingID account, the user must be paired with a mobile device. This specific device is the one the user will use for PingID online authentication. The service provider's administrator may want to unpair a mobile device from a user, for instance, when the user is switching to a new device.

This is the UnpairDevice URL:

https://idpxnyl3m.pingidentity.com/pingid/rest/4/unpairdevice/do

 

Request Body Parameters

Example reqBody object in the API payload:

"reqHeader": { ... },
"reqBody": {
 "userName": "jdoe",
 "deviceId": 64498,
 "clientData": "Session data echoed back to the requestor"
}

The parameters included in the reqBody object are:

Parameter DataType Description
userName String The username of the user to unpair from their device.
deviceId Long Optional. If set, will unpair a specific device ID from the user.
clientData String Optional. This value is returned unchanged in the API response. It can be used to save state and/or client context data for the application between API calls.

 

Response Body Parameters

Example response body:

{
 "errorId": 200,
 "errorMsg": "",
 "uniqueMsgId":"webs_sOFLeIP0EOlR-BnOCN_DTLv1uMpivQRoFN68edsYi4Y",
 "clientData": "Session data echoed back to the requestor"
}

The parameters included in the responseBody object are:

Parameter DataType Description
errorId Int A numeric error code (200 indicates a successful operation)
errorMsg String A textual description of the error, if there was one.
uniqueMsgId String A unique ID for the response message. This is logged and used to track the specific transaction for troubleshooting purposes.
clientData String The value sent in the request’s clientData field.

 

When a user has more than one device paired they can choose which of their devices will be the default device and set a nickname for each of their devices.

For example if a user pairs two iPhones they can provide them nicknames like "Personal iPhone" and "Work iPhone" and set one of them to be the default device.

This is the UpdateDeviceAttributes URL:

https://idpxnyl3m.pingidentity.com/pingid/rest/4/updatedeviceattr/do

 

Request Body Parameters

Example reqBody object in the API payload:

"reqHeader": { ... },
"reqBody": {
 "attributeName": "SET_PRIMARY",
 "attributeValue": "true",
 "userName": "jdoe",
 "deviceId": 64498,
 "clientData": "Session data echoed back to the requestor"
}

The parameters included in the reqBody object are:

Parameter DataType Description
attributeName String SET_PRIMARY - to set a device as a primary device.
NICKNAME - set a nickname to the device.
attributeValue String For attribute SET_PRIMARY set this value to “true”
For attribute NICKNAME set this value to the nickname the user selected for their device.
userName String The username of the user to update devices for.
deviceId Long The device ID to update.
clientData String Optional. This value is returned unchanged in the API response. It can be used to save state and/or client context data for the application between API calls.

 

Response Body Parameters

Example response body:

{
 "errorId": 200,
 "errorMsg": "",
 "uniqueMsgId":"webs_sOFLeIP0EOlR-BnOCN_DTLv1uMpivQRoFN68edsYi4Y",
 "clientData": "Session data echoed back to the requestor"
}

The parameters included in the responseBody object are:

Parameter DataType Description
errorId Int A numeric error code (200 indicates a successful operation)
errorMsg String A textual description of the error, if there was one.
uniqueMsgId String A unique ID for the response message. This is logged and used to track the specific transaction for troubleshooting purposes.
clientData String The value sent in the request’s clientData field.

 

The WebAuthnStartPairing API is an integral step in the FIDO security key pairing flow. The service provider initiates WethAuthn pairing using the WebAuthnStartPairing API. The WebAuthnStartPairing API returns parameter data for public key credentials.  These parameters are required as an input for the next step in the WebAuthn authentication flow, the call to the browser’s navigator.credentials.create function, which will return the public key credentials. For further information, refer to Example : PingID FIDO security key.

This is the WebAuthnStartAuth URL:

https://idpxnyl3m.pingidentity.com/pingid/rest/4/webauthnstartpairing/do

 

Request Body Parameters

Example reqBody object in the API payload:

"reqBody": {
   "rpId": "pingone.com",
   "rpName": "PingID Web Authentication",
   "userName": "fidouser1",
   "webauthnType": "WebAuthn"
}

 

The parameters included in the reqBody object are:

Parameter DataType Description

rpId

String

Domain of the service provider. The rpId that is used for pairing must be used for authentication.


rpName

String

Descriptive string or name of the provider’s service.

userName

String

The user’s PingID username.

webAuthnType

String

Set to “WebAuthn” to indicate FIDO security key pairing method.

 

Response Body Parameters

Example response body:

{
"responseBody": {
   "publicKeyCredentialOptions": "{\"rp\":{\"id\":\"pingone.com\",\"name\":\"PingID Web Authentication\"},\"user\":{\"id\":[-66,8,-83,24,113,124,39,-53,36,106,-87,75,-4,71,-83,46,-115,62,-43,59,-50,27,-56,99,46,78,-31,-120,13,-71,-8,-46],\"displayName\":\"4bc336c9-a8fa-44d0-ac8c-7bf042e064ea_fidouser1\",\"name\":\"4bc336c9-a8fa-44d0-ac8c-7bf042e064ea_fidouser1\"},\"challenge\":[-118,-57,-55,120,58,96,48,-89,97,-55,-121,-83,93,40,-108,119,62,27,-75,-70,-18,123,-48,-34,91,-6,96,-33,34,102,-39,-52],\"pubKeyCredParams\":[{\"type\":\"public-key\",\"alg\":\"-7\"},{\"type\":\"public-key\",\"alg\":\"-37\"},{\"type\":\"public-key\",\"alg\":\"-257\"}],\"timeout\":120000,\"excludeCredentials\":[],\"authenticatorSelection\":{\"authenticatorAttachment\":\"cross-platform\",\"requireResidentKey\":false,\"userVerification\":\"preferred\"},\"attestation\":\"direct\"}",
   "sessionId": "b6367b8e-1da8-490d-9c6d-6814cb2cfc81",
   "errorMsg": "",
   "errorId": 200,
   "uniqueMsgId": "webs_0vntDNAOWRwTL1W5_RbsNzuol1lu0eKfzRSJeC86QKM",
   "clientData": null
  }
}

 

Parameter DataType Description

publicKeyCredentialOptions

String

JSON structure containing parameters for retrieving the public key credentials for the FIDO security key.

sessionId

String

The session id returned from a previous call to start pairing.

errorId

Int

A numeric response code indicating the success or failure state of the API call.

errorMsg

String

Text describing the state or cause of an unsuccessful API call.

clientData

String

This value is returned unchanged in the API response. It can be used to save state and/or client context data for the application between API calls.

The WebAuthnFinishPairing API is an integral step in the FIDO security key pairing flow. The WebAuthnFinishPairing API must follow the call to the browser’s navigator.credentials.create function, which follows a WebAuthnFinishPairing API call. The navigator.credentials.create function returns the public key credentials, which are required by the WebAuthnFinishPairing API to complete the pairing process. For further information, refer to Example : PingID FIDO security key.

This is the WebAuthnFinishPairing URL:

https://idpxnyl3m.pingidentity.com/pingid/rest/4/WebAuthnFinishPairing/do

 

Request Body Parameters

Example reqBody object in the API payload:

"reqBody": {
   "rpId": "pingone.com",
   "sessionId": "b6367b8e-1da8-490d-9c6d-6814cb2cfc81",
   "userName": "fidouser1",
   "origin": "https:// admin.pingone.com",
   "publicKeyCredentialJson": "<output from navigator.credentials.create function>"
}

The parameters included in the reqBody object are:

Parameter DataType Description

rpId

String

JSON structure containing parameters for retrieving the public key credentials for the FIDO security key.

sessionId

String

The session id returned from a previous call to start pairing.

userName

String

The user’s PingID username.

origin

String

The scheme and domain of the URL that the user wants to access.

publicKeyCredentialJson

String

JSON structure comprising the public key value and metadata parameters.

 

A generic interface to asynchronously create PIngID jobs. 

This is the CreateJob URL:

https://idpxnyl3m.pingidentity.com/pingid/rest/4/createjob/do

 

Request Body Parameters

Example reqBody object in the API payload:

"reqHeader": { ... },
"reqBody": {
 "jobType": "USER_REPORTS",
 "clientData": "Session data echoed back to the requestor"
}

The parameters included in the reqBody object are:

Parameter DataType Description
jobType String Currently, this can be only "USER_REPORTS".
clientData String Optional. This value is returned unchanged in the API response. It can be used to save state and/or client context data for the application between API calls.

 

Response Body Parameters

Example response body:

{
 "jobToken": "DTLv1uMpivQRoFN68edsYi4Y",
 "clientData": "Session data echoed back to the requestor"
}

The parameters included in the responseBody object are:

Parameter DataType Description
jobToken String The token assigned to this job. This token is used by other APIs (such as GetJobStatus) to reference this job.
clientData String The value sent in the request’s clientData field.

 

Retrieve the status of a job created by a CreateJob operation.

This is the GetJobStatus URL:

https://idpxnyl3m.pingidentity.com/pingid/rest/4/getjobstatus/do

 

Request Body Parameters

Example reqBody object in the API payload:

"reqHeader": { ... },
"reqBody": {
 "jobToken": "DTLv1uMpivQRoFN68edsYi4Y",
 "clientData": "Session data echoed back to the requestor"
}

The parameters included in the reqBody object are:

Parameter DataType Description
jobToken String A jobToken value returned by CreateJob. Use this token to get the status of a particular job.
clientData String Optional. This value is returned unchanged in the API response. It can be used to save state and/or client context data for the application between API calls.

 

Response Body Parameters

Example response body:

{
 "jobStatus": "pending",
 "clientData": "Session data echoed back to the requestor"
}

The parameters included in the responseBody object are:

Parameter DataType Description
jobStatus String The current status of the referenced job. This can be any one of the following: "done", "in_progress", "failure", "pending".
clientData String The value sent in the request’s clientData field.

 

Retrieves an open stream of the last completed User Reports job.

This is the GetOrganizationReport URL:

https://idpxnyl3m.pingidentity.com/pingid/rest/4/getorgreport/do

 

Request Body Parameters

Example reqBody object in the API payload:

"reqHeader": { ... },
"reqBody": {
 "fileType": "JSON",
 "clientData": "Session data echoed back to the requestor"
}

The parameters included in the reqBody object are:

Parameter DataType Description
fileType String The file format to use for the report. This can be only: "CSV" or "JSON".
clientData String Optional. This value is returned unchanged in the API response. It can be used to save state and/or client context data for the application between API calls.

 

Response Body Parameters

The response body is an open stream. Typically, the client sends the stream to a local file.