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.

Online Pairing Workflow

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

Offline Pairing Workflow

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

YubiKey Pairing Workflow

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

FIDO pairing workflow

When a user wants to pair a FIDO security key or a FIDO supported biometrics device, 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 pairing process for the FIDO security key or FIDO supported biometrics device.
For further information, refer to:

• Example : PingID FIDO security key
• Example : PingID FIDO biometrics

PingID supports use cases of FIDO hybrid mode authentication, where a custom UI (not hosted by PingID) is used for registration, while PingID’s out of the box UI is used for authentication. PPM request, which was originally developed to support authentication, also supports explicit FIDO registration. For further information see PPM request for FIDO authentication with a hybrid UI.

User Status Values

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.

Activation code redirect link for Online Pairing

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 activation code link to display to the user within a mobile application:

1. Create a string “act_code=<activation_code>”, where <activation_code> is the numeric code you received in the GetActivationCode response.
2. Encode this value with Base64, and add it as a query parameter to the redirect URL (https://idpxnyl3m.pingidentity.com/pingid/QRRedirection).

This URL will redirect the user to the PingID mobile app, and will use the activation code to pair the user:

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

Generating QR Codes from redirect links

To show an activation QR code within a web application, generate a QR code from the above redirect link, using any supported library, for example: com.google.zxing.qrcode.QRCodeWriter.

AddUser

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",
 "deviceType": "DESKTOP"
}

The parameters included in the reqBody object are:

Response Body Parameters

Example response body:

{
 "userDetails": {
  "email": "jdoe@jdoe.com",
  "lname": "Doe",
  "userEnabled": false,
  "fname": "John",
  "spList": [],
  "lastLogin": null,
  "deviceDetails": null,
  "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:

The userDetails parameters:

The deviceDetails list (one or more objects):

The spList list (an object):

GetUserDetails

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:

Response Body Parameters

Example response body:

{
 "userDetails": {
 "email": "jdoe@gmail.com",
 "userName": "jdoe",
 "lname": "",
 "spList": [],
 "lastLogin": null,
 "deviceDetails": null,
 "userEnabled": false,
 "fname": "Johnny",
 "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:

The userDetails parameters:

The deviceDetails list (one or more objects):

The spList list (an object):

EditUser

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.

When using edituser, keep in mind that all of the existing details for the specified user will be cleared. So if, for example, the existing user details include an email address, make sure to provide the email address in the payload of reqBody when you call edituser. Any fields that you do not include will be set to null.

Therefore, the recommended way to use edituser is to first call getuserdetails, and then use the returned object as the basis for the object that you are including for the edituser call.

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:

Response Body Parameters

Example response body:

{
 "userDetails": {
  "email": "jdoe@jdoe.com",
  "lname": "Doe",
  "userEnabled": false,
  "fname": "Johnny",
  "spList": [],
  "lastLogin": null,
  "deviceDetails": null,
  "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:

The userDetails parameters:

The deviceDetails list (one or more objects):

The spList list (an object):

DeleteUser

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:

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:

SuspendUser

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:

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:

ActivateUser

After a user has been suspended by calling SuspendUser, you can reactivate the user by calling ActivateUser. Depending on the user status, ActivateUser optionally generates an activation code as part of an activation process. See the activationCode parameter description in the response body, that lists the conditions for ActivateUser to generate an activation code.

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",
 "deviceType": "DESKTOP"
}

The parameters included in the reqBody object are:

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:

addservice

Ordinarily, a user is added to a PingID service such as the PingID integration with Windows login the first time that they log in and perform a successful MFA. However, if there is a situation where you want to set a bypass for a new user for a specific service such as the Windows login, you must first manually add them to the service using the addservice endpoint and then submit a request using the userbypass endpoint with the relevant service as a parameter. For more information, see ToggleUserBypass.

URL to use:

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

Request Body Parameters

Example reqBody object in the payload:

"reqHeader": { ... },
"reqBody": {
  "userName": "joe",
  "spAlias": "winlocal"
}

The parameters included in the reqBody object are:

Response Body Parameters

Example response body:

{
  "clientData": null,
  "errorId": 200,
  "errorMsg": "ok",
  "uniqueMsgId": "webs_jiPPOV2bTiCa0Tg0kGqMonYYnYlo2gU45WDwECNykmk"
}

The parameters included in the responseBody object are:

ToggleUserBypass

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.

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",
  "spAliases": [
    "winlocal",
    "winremote"
  ], 
  "clientData": "Session data echoed back to the requestor"
}

The parameters included in the reqBody object are:

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:

GetActivationCode

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 enters 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",
 "deviceType": "DESKTOP",
 "hoursUntilExpiration": 168
}

The parameters included in the reqBody object are:

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:

GetPairingStatus

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 returned 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:

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:

StartOfflinePairing

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:

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:

FinalizeOfflinePairing

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:

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:

OfflinePairing

OfflinePairing pairs the user so that they can later authenticate with the method that was specified - email, SMS, voice message, OATH token, or authenticator app. (Note that 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:

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:

PairYubiKey

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:

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:

OATH token management

resyncoathtoken

Hardware tokens need to maintain time synchronization. If a token returns an error, it needs to be resynchronized.

PingID supports resyncing the token, one OTP at a time. The caller provides the first OTP. If the OTP is valid, then the status 30016 is returned together with a sessionId in the response body. The caller can make another resync call with the next OTP and the sessionId to complete the resync process.

This is the resyncoathtoken URL:

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

Request Body Parameters

Example reqBody object in the API payload:

The parameters included in the reqBody object are:

Single-step resync example

In a single-step resync process, two OTPs are provided in one request:

Single-step resync request

"reqBody": { 
   "serialNumber": "123321", 
   "otps": ["112814","889429"], 
   "initiatedBy": "ADMIN" 
}

Single-step resync response

Completion of a successful resync returns the HttpStatus=200 errorId=200 values.

{
 "responseBody": {
 "clientData": null,
 "errorId": 200,
 "errorMsg": "OK",
 "sessionId": null,
 "uniqueMsgId": "webs_V-12nF20Q6iSj7oyunUlN6uLc15k_fxp5KzsIfycDy0"
 }
}

Two-step resync example

In a two-step resync process, each OTP is provided, one at a time.

Two-step resync process (first step request)

"reqBody": { 
   "serialNumber": "123321", 
   "otps": ["112814"], 
   "initiatedBy": "ADMIN" 
}

Two-step resync process (first step response)

Successful completion of a the first step of a two-step resync returns the HttpStatus=200 errorId= 30016 values.

{
 "responseBody": {
 "clientData": null,
 "errorId": 30016,
 "errorMsg": "To resync this token, wait for the next passcode on your device and enter it.",
 "sessionId": "oarys_BQ413MplMhO0m2mN1vEha4lurBfJqHq756UbMfLQ-yA",
 "uniqueMsgId": "webs_Temma_l5cGnS2cF8v4xPO1kQmhcwzh5nRGHhNhzW4dk"
 }
}

Two-step resync process (second step request)

The request in the second step uses the sessionId that was returned in the response of the first step request.

"reqBody": {
 "serialNumber": "123321",
 "otps": ["222973"],
 "initiatedBy": "ADMIN",
 "sessionId": "oarys_M0lbkATkRWXH3bHcWrmTRpISAr6TKVFRcjUvnPSq0sk"
 }

Two-step resync process (second step response)

Successful completion of a the second step of a two-step resync returns the HttpStatus=200 errorId=200 values.

{
 "responseBody": {
 "clientData": null,
 "errorId": 200,
 "errorMsg": "OK",
 "sessionId": null,
 "uniqueMsgId": "webs_riJIWfq_XQvpW0oJLpSCqGc3pm1ZOroyUB1nG_xAn7U"
 }
}

createorgtokens

You can use the createorgtokens endpoint to upload a list of OATH tokens that can then be mapped to individual users.

This is the createorgtokens URL:

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

Request Body Parameters

Example reqBody object in the API payload:

"reqHeader": { ... },
"reqBody": {
  orgAlias: "111111111111111111111111111111",
  tokens: [
    {
      serialNumber: "1",
      tokenType: "TOTP",
      secretKey: "AAAAAAAAAAAAAAAAAAAAAAAAAAA",
      otpLength: "6",
      timeStep: "30"
    },
    {
      serialNumber: "2",
      tokenType: "TOTP",
      secretKey: "EEEEEEEEEEEEEEEEEEEEEEEEEE",
      otpLength: "6",
      timeStep: "30"
    }
  ]
}

The parameters included in the reqBody object are:

Response Body Parameters

The response body contains a jobToken field. You can then use the value of this field with the getjobstatus endpoint to retrieve the results of the upload attempt (see GetJobStatus).

Example response body:

{
  "responseBody": {
    "clientData": null,
    "errorId": 200,
    "errorMsg": "ok",
    "jobToken": "XXXXXJobTokenXXXXXX",
    "uniqueMsgId": "webs_XXXX"
  }
}

When you use the value of jobToken in a getjobstatus request, the response looks like this:

{
  "responseBody": {
    "clientData": null,
    "errorId": 200,
    "errorMsg": null,
    "status": "done",
    "jobResult": {
      "type": "CreateOath",
      "status": "DONE",
      "duplicates": [
        {
          "row": "",
          "serial": "1",
          "password": "1xxxxx"
        },
        {
          "row": "",
          "serial": "12",
          "password": "1xxxxxx"
        }
      ],
      "numberOfDuplicates": 2
    },
    "uniqueMsgId": "webs_NqLdXuJacyohO7SJG08q0hMLIiknQbEsfPoy47HnVo0"
  }

If there is already an existing token with the same serial number as a token you are trying to create, the remaining tokens are created, but there is no attempt to recreate the duplicate tokens.

• jobResult.numberOfDuplicates indicates how many tokens in the request already exist.
• If there were no duplicates, the jobResult.duplicates array will be empty. Otherwise, it will include the basic information for each of the tokens that were identified as duplicates: the serial number of the existing token (jobResult.duplicates.serial) and its secret key (jobResult.duplicates.password).

revokeorgtokens

You can use the revokeorgtokens endpoint to revoke one or more OATH tokens that you previously uploaded for use.

This is the revokeorgtokens URL:

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

Request Body Parameters

Example reqBody object in the API payload:

"reqHeader": { ... },
"reqBody": {
  orgAlias: "1111111111111111111",
  unpairBeforeDelete: false,
  serialNumbers: ["72","107"]
}

The parameters included in the reqBody object are:

Response Body Parameters

The response body contains a jobToken field. You can then use the value of this field with the getjobstatus endpoint to retrieve the results of the upload attempt (see GetJobStatus).

Example response body:

{
  "responseBody": {
    "clientData": null,
    "errorId": 200,
    "errorMsg": "ok",
    "jobToken": "XXXXXJobTokenXXXXXX",
    "uniqueMsgId": "webs_XXXX"
  }
}

When you use the value of jobToken in a getjobstatus request, the response will look like this if the revokeorgtokens request succeeded:

{
  "responseBody": {
    "clientData": null,
    "errorId": 200,
    "errorMsg": null,
    "status": "done",
    "jobResult": {
      "type": "JobResult",
      "status": "DONE"
    },
    "uniqueMsgId": "webs_xxxxxx"
  }
}

If one or more of the tokens to revoke is paired to a user, and you did not set the unpairBeforeDelete parameter to true, the entire revoke request fails. In such cases, the response includes a message field that explains the problem and a pairedSerials object that lists the serial numbers of the paired tokens and the username of the user that each is paired with:

{
  "responseBody": {
    "clientData": null,
    "errorId": 200,
    "errorMsg": null,
    "status": "failure",
    "jobResult": {
      "type": "RevokeOathTokensJobResult",
      "status": "FAILURE",
      "pairedSerials": {
        "12345": "username"
      },
      "message": "The following tokens cannot be deleted because they are currently paired to users."
    },
    "uniqueMsgId": "XXXXXXXXXX"
  }
}

UnpairDevice

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:

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:

UpdateDeviceAttributes

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:

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:

AuthenticatorAppStartPairing

The call to AuthenticatorAppStartPairing causes PingID to generate a pairing key URI which should be embedded in a QR code, and a matching pairing key which allows the user to pair manually.

The user scans the QR code or manually pairs the authenticator app. Then, in the service provider’s application, the user must manually enter the OTP that is displayed in the authenticator app. To complete the pairing process, the service provider’s application should then call AuthenticatorAppFinishPairing while providing the OTP.

This is the AuthenticatorAppStartPairing URL:

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

Request Body Parameters

Example reqBody object in the API payload:

"reqHeader": { ... },
"reqBody": {
 "username": "jdoe",
 "pairingType": "TOTP"
}

The parameters included in the reqBody object are:

Response Body Parameters

Example response body:

{
 "sessionId": "oacts_rxodmgpbVkjVltIBVP7C7m6y6ddsOY-a8BYqpDHHxZY",
 "errorId": 200,
 "errorMsg": "",
 "uniqueMsgId":"webs_sOFLeIP0EOlR-BnOCN_DTLv1uMpivQRoFN68edsYi4Y",
 "pairingKeyUri": "otpauth://totp/MyOrg%3Ajdoe%myorg.com?secret=RRHWKYHJZAYBEONJREBUTW3GKL2VLZK2&issuer=MyOrg",
 "pairingKey":"RRHW KYHJ ZAYB EONJ REBU TW3G KL2V LZK2"
}

The parameters included in the responseBody object are:

AuthenticatorAppFinishPairing

The call to AuthenticatorAppFinishPairing completes the pairing process initiated by calling AuthenticatorAppStartPairing. The user enters the OTP which is displayed on the Authenticator App.

This is the AuthenticatorAppFinishPairing URL:

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

Request Body Parameters

Example reqBody object in the API payload:

"reqHeader": { ... },
"reqBody": {
 "sessionId": "oacts_rxodmgpbVkjVltIBVP7C7m6y6ddsOY-a8BYqpDHHxZY",
 "otp": "123456"
}

The parameters included in the reqBody object are:

Response Body Parameters

Example response body:

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

The parameters included in the responseBody object are:

WebAuthnStartPairing (FIDO security key, FIDO biometrics, FIDO2 devices)

The WebAuthnStartPairing API is an integral step in the pairing flow for FIDO security keys, FIDO biometrics, and FIDO2 devices. 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, see Example : PingID FIDO security key and Example : PingID FIDO biometrics.

This is the WebAuthnStartPairing URL:

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

Request Body Parameters

Example reqBody object for security key:

"reqBody": {
   "rpId": "pingone.com",
   "rpName": "PingID Web Authentication",
   "userName": "fidouser1",
   "webauthnType": "WebAuthn",
   "name": "User1",
   "displayName": "User1@pingidentity.com"
}

Example reqBody object for biometrics:

"reqBody": {
   "rpId": "pingone.com",
   "rpName": "PingID Web Authentication",
   "userName": "fidouser1",
   "webauthnType": "webauthn_platform",
   "name": "User1",
   "displayName": "User1@pingidentity.com"
}

The parameters included in the reqBody object are:

Response Body Parameters

Example response body:

{
  "responseBody": {
    "clientData": null,
    "errorId": 200,
    "errorMsg": "",
    "sessionId": "9652e5e9-b698-4495-8038-c2f440596972",
    "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\":\"fidouser1@pingidentity.com\",\"name\":\"fidouser1@pingidentity.com\"},\"challenge\":[-110,61,102,122,-28,-117,-55,-65,-101,6,108,89,-70,-75,-31,54,37,-75,-116,-25,13,-113,-49,17,-10,-11,118,-116,87,56,17,35],\"pubKeyCredParams\":[{\"type\":\"public-key\",\"alg\":\"-7\"},{\"type\":\"public-key\",\"alg\":\"-37\"},{\"type\":\"public-key\",\"alg\":\"-257\"}],\"timeout\":120000,\"excludeCredentials\":[],\"authenticatorSelection\":{\"authenticatorAttachment\":\"platform\",\"requireResidentKey\":false,\"userVerification\":\"preferred\"},\"attestation\":\"direct\"}",
    "uniqueMsgId": "webs_ohi_K2NBLZnZpR-avezCrtaKQUwsyKGt4aSXwtD6rEg09so"
  }
}

The parameters included in the responseBody object are:

WebAuthnFinishPairing (FIDO security key, FIDO biometrics, FIDO2 devices)

The WebAuthnFinishPairing API is an integral step in the pairing flow for FIDO security keys, FIDO biometrics, and FIDO2 devices. The WebAuthnFinishPairing API must follow the call to the browser’s navigator.credentials.create function, which follows a WebAuthnStartPairing 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, see Example : PingID FIDO security key and Example : PingID FIDO biometrics.

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:

PingID Services

In this context, PingID services refers to the type of integration with PingID that is being used, for example, the PingID integration with Windows login.

A number of endpoints can take a service as an optional parameter, for example, userbypass.

A parameter representing the PingID service is also used in authentication flows, where the relevant parameter uses the value web.

The parameter for specifying the PingID service is usually called spAlias.

The following table lists the different values that can be used for the service parameter and explains what each value represents.

Job Management

Running Jobs

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”.

CreateJob

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:

Response Body Parameters

Example response body:

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

The parameters included in the responseBody object are:

GetJobStatus

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:

Response Body Parameters

Example response body:

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

The parameters included in the responseBody object are:

GetBulkJobStatus

Accepts a list of job tokens, and returns a map of the job tokens and their statuses.

This is the GetBulkJobStatus URL:

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

Request Body Parameters

Example reqBody object in the API payload:

“reqBody”: {
 “jobTokens”:[“Fg9bVV8BVlpZWRdNRERaVVoHSFdBXhBUSAheAgtTUwwRUUMc”,“FFpeBFxVVg1ZCkIfFkRaVwxUSFYSWEdUFAwIVwhRVApFDExB”],
 }

The parameters included in the reqBody object are:

Response Body Parameters

Example response body:

{
 “responseBody”: {
   “clientData”: null,
   “errorId”: 200,
   “errorMsg”: null,
   “uniqueMsgId”: “webs_nkzHr4xGLvmnh33y-HPD1UZmJDP85P_KlOD1V3aA79Y”,
   “jobResults”: {
     “FFpeBFxVVg1ZCkIfFkRaVwxUSFYSWEdUFAwIVwhRVApFDExB”: {
       “status”: “DONE”,
       “type”: “JobResult”
     },
     “Fg9bVV8BVlpZWRdNRERaVVoHSFdBXhBUSAheAgtTUwwRUUMc”: {
       “status”: “DONE”,
       “type”: “JobResult”
     }
   }
 }
}

The parameters included in the responseBody object are:

GetOrganizationReport

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:

Response Body Parameters

The response body is an open stream. Typically, the client sends the stream to a local file. The output report file has the following layout: