Authentication API

A PingID authentication request can be fulfilled by two methods depending on the account configuration, the users preferences and the users devices available at the time of the authentication:

  • Online Authentication - used to trigger an authentication action on an end-user's device (i.e. a fingerprint or swipe action). This process uses the AuthenticateOnline API operation.
  • Offline Authentication - used to validate a one-time password (OTP) provided to the end-user (either via the PingID app, email, SMS, voice or by a YubiKey). This process uses the AuthenticateOffline operation which is always called after an AuthenticateOnline operation.

In version 4.9 and higher of the API, an authentication request will commence by calling the StartAuthentication operation. This operation will determine the appropriate workflow to perform based on the configuration of the PingOne account.

 

Each authentication should start by calling the StartAuthentication operation. The StartAuthentication response will guide the developer on how to proceed with the authentication, depending on the account configuration the users preferences and whether the users devices are available at the time of the authentication. The account preference that is evaluated is the "Multiple Devices" mode option available in the administration console.

The Multiple Devices mode has two options:

  • Device Selection Mode - The user should be displayed with a list of his available devices and select the device he wants to authenticate with.
  • Default Device Mode - The user has a default (primary) device to be used by default, the list of other available devices can displayed if the user chooses to change the authentication device by canceling the currently active authentication.

The response of StartAuthentication includes information that is vital to the rest of the authentication flow including a session ID that is used throughout the flow and should be passed with every call in this flow, the list of user devices and a flag indicating whether the account has the multiple devices mode enabled. After parsing the response, one of the following three flows will apply:

  • Device selection flow - display the list of available devices to the user. Once the user selects a device, StartAuthentication should be called again with the selected device ID and the session ID from the original StartAuthentication response.
  • Online Authentication - The user has configured a preference for authentication by PingID mobile application.
  • Offline Authentication - The user has configured a preference for authentication by SMS, voice message, email, desktop or YubiKey.

For example, the following sequence describes a StartAuthentication flow:

  1. The service provider triggers a StartAuthentication request to the PingID service along with the authenticating user's username.
  2. The PingID service will response with a message indicating either to:
        a) Continue with either the online or offline authentication flow with a specific device ID
        b) Display a list of devices to the user so they can select a device to use
  3. If the result was b) to display the list of devices, the application should prompt the user to select the device, then re-submit a StartAuthentication request passing along the device ID the user selected.

 

The CancelAuthentication operation is used to cancel an active, ongoing, authentication. In a scenario where the user started an authentication with one device and decided they want to change their authentication device, CancelAuthentication should be called to cancel the currently active authentication.

This step is mandatory for online authentication done with a mobile app, since the mobile app cannot have more than one active authentication running at any given time. Although this step is not mandatory for other authentication devices types (SMS, voice message, email, desktop or Yubikey), it is highly recommended.

For example, the following sequence describes a CancelAuthentication flow when the user authenticates by the PingID mobile application to a service provider:

  1. The service provider triggers a StartAuthentication request to the PingID server along with the authenticating user's username.
  2. PingID server responds with:
    Appropriate action to take based on account settings (in this example, the AuthenticateOnline flow)
    List of devices associated with the user (in this example, the default device will be used for multi-factor authentication)
    Session ID
  3. The service provider sends an AuthenticateOnline request to the PingID service.
  4. The PingID server pushes an authentication request to the user’s mobile device.
  5. The service provider displays a “Please wait...” screen which includes an option for the user to change their authentication device.
  6. In this scenario the user does not have their mobile phone with them, and chooses to change their authentication device.
  7. The service provider sends CancelAuthentication request to the PingID server.
  8. The service provider displays the list of devices paired for the user that were received with the response to the initial StartAuthentication call.
  9. The user selects an alternate device.
  10. The service provider starts the authentication flow again by calling StartAuthentication, passing the username and device ID of the alternate device.
     

Online authentication is performed when all of the following conditions apply:

  • The user has configured a preference for online authentication.
  • The user’s device is accessible over the internet.
  • The user’s device can receive push notifications.

Usually, online authentication is performed after the user has entered username and password values. The user is prompted to authenticate using the PingID mobile application. The PingID server is notified of the verification action, and it notifies the service provider that authentication has succeeded, and the user can enter the requested application.

Note: In PingID API version 4.9 and higher, the initial authentication request should start with the start authentication operation.

This is the sequence of events in the online authentication workflow example, described in the diagram below:

  1. The service provider sends an online authentication request to the PingID server along with the username.
  2. The PingID server pushes a message to the user’s mobile device, prompting the user to swipe a button displayed in the message, or to perform fingerprint identification.
  3. The user swipes the button or submits a valid fingerprint, and a verification message is sent to the PingID server.
  4. The PingID server sends a success message to the service provider, which now allows the user to login to the requested application.
 

 

 

Offline authentication is performed when one of the following conditions applies:

  • The user has configured a preference for authentication by SMS, voice message, email or YubiKey.
  • The user’s device is inaccessible over the internet.
  • The user’s device cannot receive push notifications (due to a firewall or other local restrictions).

In this case, the user must manually enter a one-time password which is generated by the PingID mobile or desktop application, by a YubiKey, sent via SMS, voice message or email, depending on the situation.

Note: The OTP used for offline authentication is an HOTP – an HMAC-based one-time password.

This is the sequence of events in the offline authentication workflow example described in the diagram below:

  1. The service provider sends a start authentication request to the PingID server along with the username.
  2. The PingID server sends either a “device unreachable” status, or the OTP access method configured by the user, to the service provider, together with a session ID.
  3. The service provider prompts the user to enter a one-time password.
  4. The user retrieves the OTP from the appropriate source, then enters it in the service provider’s prompt page.
  5. The service provider sends an offline authentication request, containing the OTP that the user entered and the session ID it received, to the PingID server.
  6. The PingID server sends a success message to the service provider, which now allows the user to login to the requested application.

 

 

 

When a user wants to authenticate using a FIDO2 or U2F security key, the service provider initiates the authentication process with the StartAuthentication API, which acts as a flow manager for the authentication process. The StartAuthentication API checks policies and other factors, and when relevant, returns a status (errorId 30011) to indicate that the security key must be used. 
The service provider then invokes the WebAuthnStartAuth 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.get" function, which is the next step in the WebAuthn authentication flow. The "navigator.credentials.get" function returns the public key credentials. The AuthOffline API then uses public key credentials and input parameters in its request body, and completes the FIDO security key authentication. For further information, refer to Example : PingID FIDO security key.

Some organizations use a 3rd-party hardware device called a “YubiKey” (produced by Yubico) to generate One-Time Passwords. PingID enables integration with this type of device. To authenticate a user who is using a YubiKey, the Service Provider uses offline authentication, while providing the OTP generated by the YubiKey, which the user enters manually. In this authentication mode, users are paired with YubiKey devices rather than with mobile devices.

 

When an organizations user want to access a service that is protected by PingID MFA, the service provider will first use StartAuthentication. For example, a customer wants to logon to an online banking service, or an employee wants to access the organizations email platform. After the user enters a username and password and clicks a “Login” button, the service provider sends a StartAuthentication request to the PingID service. The response will return all the necessary information required to complete the authentication. Start authentication takes into consideration the account’s multiple devices configuration, the device selection mode configuration, the users preferences and the users devices available at the time of the authentication.

This is the StartAuthentication URL:

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

 

Request Body Parameters

Example reqBody object in the API payload:

"reqHeader": { ... },
"reqBody": {
  "spAlias": "web",
  "userName": "marcher",
  "deviceId": 284159158921096000,
  "sessionId": "webs_jRyBWbUG87sYYh2UlG-TBoVNC6A8kXadFtj4qCMGrl4",
  "clientData": "Session data echoed back to the requestor",
    "formParameters": {
        "isWebAuthnSupportedByBrowser": "true"}
}

The parameters included in the reqBody object are:

 

Parameter DataType Description
spAlias String Set this parameter's value to "web" to indicate a web authentication.
userName String The user’s PingID username.
deviceId Long To specify a specific device to authenticate with. (In device selection mode, the first call will return a list of devices for the user to choose from, a second call is done with a session id and a device id in the request to specify the exact device to authenticate with).
sessionId String The session id returned from a previous call to start authentication.
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.
formParameters Map
<String, String>

Optional key/value pairs.
The "isWebAuthnSupportedByBrowser" key has a default value of "true", making the assumption that the client browser supports WebAuthn. In the case of a FIDO security key flow, the client browser’s ability to support WebAuthn should be checked before activating this API.
If the browser does not support WebAuthn, this API will fail, returning HTTP status 400 with error code 20570 (WEBAUTHN_NOT_SUPPORTED_BY_BROWSER), since it cannot find the “navigator.credentials.get” and “navigator.credentials.create” JavaScript functions.
Set the “isWebAuthnSupportedByBrowser” to “false” when the browser does not support WebAuthn. When “isWebAuthnSupportedByBrowser” is “false”, FIDO devices will be ignored, and the server will attempt to retrieve and list the user’s next device (if multiple devices exist for that user).

Refer to Example : PingID FIDO security key.


Response Body Parameters

Example response body:

"responseBody": {
  "extendedAuthenticationDetails": {
    "adminHelp": "Contact your system administrator",
    "gracePeriod": 1454076723000,
    "lastSuccessfulLogin": 1453991562000
  },
  "userDevices": [ 
    "deviceDetails": {
      "email": null,
      "appVersion": "1.6.2(OE5700)",
      "hasWatch": false,
      "countryCode": null,
      "sentClaimedSms": -1,
      "phoneNumber": null,
      "nickname": "username",
      "deviceModel": "samsung SM-G920F",
      "enrollment": "2016-01-11 07:03:14.371",
      "availableNotClaimedSms": 0,
      "availableClaimedSms": 0,
      "deviceRole": "PRIMARY",
      "pushEnabled": true,
      "deviceId": 284159158921096000,
      "sentNotClaimedSms": -1,
      "type": "Android",
      "osVersion": "5.1.1"
    },
    "deviceDetails": {
      "email": null,
      "appVersion": null,
      "hasWatch": false,
      "countryCode": null,
      "sentClaimedSms": -1,
      "phoneNumber": null,
      "nickname": "YubiKey",
      "deviceModel": null,
      "enrollment": "2016-02-09 08:04:08.023",
      "availableNotClaimedSms": 0,
      "availableClaimedSms": 0,
      "deviceRole": "SECONDARY",
      "pushEnabled": false,
      "deviceId": 285234913243546570,
      "sentNotClaimedSms": -1,
      "type": "YubiKey",
      "osVersion": null
    } ],
  "multipleDevicesEnabled": true,
  "sessionId": "webs_COQgngDLjctrLWRMObANUrKkHVbk46OtVL4Uo35XcZ8",
  "errorId": 30007,
  "errorMsg": "Continue the authentication flow using online flow",
  "uniqueMsgId": "webs_COQgngDLjctrLWRMObANUrKkHVbk46OtVL4Uo35XcZ8",
  "clientData": "Session data echoed back to the requestor"
}

The parameters included in the responseBody object are:

Parameters DataType Description
clientData String The value sent in the request’s clientData field.
errorId Int A numeric response code. For multiple devices, the following values can be used to evaluate the next action to take:
  • 30001 - Offline authentication (SMS)
  • 30002 - Offline authentication (Voice)
  • 30003 - Offline authentication (Application)
  • 30004 - Offline authentication (YubiKey)
  • 30005 - Offline authentication (Email)
  • 30007 - Online authentication (Application)
  • 30008 - Device selection prompt
  • 30011 – Offline authentication (FIDO security key)
errorMsg String A textual description of the response, if there was one.
sessionId String The session ID will be used with other calls in the flow, may be used in an online authentication flow, offline authentication flow or  in a second start authentication flow.
uniqueMsgId String A unique ID for the response message. This is logged and used to track the specific transaction for troubleshooting purposes.
extendedAuthenticationDetails Object Contains additional information used by the authentication process. See details in the extendedAuthenticationDetails table below.
userDevices Array A list of one or more deviceDetails objects containing information about the user's paired devices. See details in the deviceDetails table below.
multipleDevicesEnabled Boolean Indicates whether the multiple devices feature is enabled for the account.

The extendedAuthenticationDetails object:

Parameters DataType Description
adminHelp String Descriptive prompt the application can display to direct the end user for help.
gracePeriod DateTime (epoch) When the grace period to allow bypassing PingID authentication expires  (in UNIX epoch format).
lastSuccessfulLogin DateTime (epoch) Last time this user successfully authenticated  (in UNIX epoch format).

The deviceDetails objects (one or more objects) in the userDevices list:

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 remaining available times within the current day that the user can request an OTP via SMS or voice message, without using the OTP for authentication. This value is reset daily (it is limited because of the costs incurred for the user).
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 (null if offline authentication is configured).

The cancel authentication operation can be used to cancel an in progress authentication when a user wishes to change their authentication device after the authentication flow has commenced.

This is the CancelAuthentication URL:

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

 

Request Body Parameters

Example reqBody object in the API payload:

"reqHeader": { ... },
"reqBody": {
  "cancelAuthenticationType": "CHANGE_DEVICE",
  "sessionId": "webs_IAjpPLQ5nKz2DPZCbOXVhA5-JaeIVqOMExTK03NuF6k",
  "clientData": "Session data echoed back to the requestor"
}

The parameters included in the reqBody object are:

Parameter DataType Description
cancelAuthenticationType String

The reason for canceling the authentication, also displayed at the mobile applications cancellation screen. Values:

  • CHANGE_DEVICE - The user wants to change the authentication device.
  • ADD_DEVICE - The user wants to manage their devices. (they will need to authenticate to get into the self service device management screen)
  • DEFAULT - a generic reason.
sessionId String The session id return from a previous call to start authentication.
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:

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

The parameters included in the responseBody object are:

Parameters DataType Description
clientData String The value sent in the request’s clientData field.
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.

 

When an organization’s user want to access a service that is protected by PingID authentication, the service provider will first try to use online authentication. For example, a customer wants to logon to an online banking service, or an employee wants to access the organization’s email platform. After the user enters a username and password and clicks a “Logon” button, the service provider sends an AuthenticateOnline request to the PingID service. If the operation is successful, PingID pushes a message to the user’s mobile device, requesting the user to swipe a button or scan a fingerprint. When the user has performed this action, the service provider allows the user to proceed to its entry page.

When you attempt online authentication and the device is not reachable or does not claim the request (for example, the device's lock screen prevents it), the authentication process enters offline mode. You can then use the AuthenticateOffline operation or retry AuthenticateOnline.

When you attempt online authentication and the device claims the request (opens the app), but the user does not respond in time, the authentication process remains in online mode. The intent is that online authentication will then be attempted again.

This is the AuthenticateOnline URL:

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

 

Request Body Parameters

Example reqBody object in the API payload:

"reqHeader": { ... },
"reqBody": {
  "formParameters": {
    "sp_name": "My Application",
    "sp_logo": "https://www.mycorp.com/images/myapp.png",
    "org_logo": "https://www.mycorp.com/images/org_logo.png",
    "bg_color": "#ADADAD",
    "bg_image": "https://www.mycorp.com/images/bg_image.png",
    "FirstTimeAfterPairing": "false"
  },
  "spAlias": "web",
  "userName": "marcher",
  "authType": "CONFIRM",
  "deviceId": 2841591,
  "clientData": "Session data echoed back to the requestor"
}

The parameters included in the reqBody object are:

Parameter DataType Description
authType String

Type of authentication mechanism to use. This is one of the following values:

CONFIRM
Use the authentication type configured in the PingID account settings.

FINGERPRINT_PERMISSIVE
Use fingerprint authentication only if the user has configured this preference.

FINGERPRINT_RESTRICTIVE
Use fingerprint authentication for any device that supports it, regardless of user configuration.

FINGERPRINT_HARD_RESTRICTIVE
Enforce fingerprint authentication for any device that supports it, regardless of user configuration, and do not allow authentication using banner messages.

OTP
Force the PingID server to return immediately to perform an OTP authentication only (rather than prompt or wait for the online authentication flow to complete).

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.
spAlias String Set this parameter's value to "web" to indicate a web authentication.
userName String The user’s PingID username.
deviceId Long To specify a specific device to authenticate with. (if not specified, the authentication request will be sent to the default device)
formParameters Object Additional parameters used to customize the authentication. See table below.

The formParameters object can contain the following parameters:

Parameter DataType Description
sp_logo String (URL) A URL pointing to an image file of the service provider's logo (PNG file), which is displayed within the PingID application during authentication.
sp_name String The name of the service requesting authentication, which is displayed within the PingID app during authentication.
org_logo String (URL) A URL pointing to an image to use as the "organization" logo (the company icon at the top of the PingID authentication screen.
bg_color String A HEX color code for the PingID authentication screen background color.
bg_image String (URL) A URL pointing to an image to use as the background of the PingID authentication screen.
FirstTimeAfterPairing Boolean Indicates whether this is the first time that authentication is requested after a device was paired with this user. This flag can be used to display a "successful pairing" message during authentication.

 

Response Body Parameters

Example response body:

{
 "extendedOnlineDetails": {
   "lastSuccessfulLogin": 1437646014000,
   "deviceOSVersion": "4.1.2",
   "deviceFp": "bWxjelNMUEEyUzZEQ0J6NFBqcmE=",
   "performedFormType": "SLIDER",
   "gracePeriod": 1436335200000,
   "adminHelp": "",
   "deviceType": "Android",
   "gpsLocation": {
    "altitude": 297.79999999999995,
    "latitude": 39.748881,
    "longitude": -104.993769,
    "accuracy": 20
   }
 },
 "sessionId": null,
 "errorMsg": "",
 "uniqueMsgId":"webs_sOFLeIP0EOlR-BnOCN_DTLv1uMpivQRoFN68edsYi4Y",
 "errorId": 200,
 "clientData": "Session data echoed back to the requestor"
}

The parameters included in the responseBody object are:

Parameters DataType Description
clientData String The value sent in the request’s clientData field.
errorId Int A numeric error code.
errorMsg String A textual description of the error, if there was one.
sessionId String If online authentication fails for any reason, the session ID will be used when requesting offline authentication.
uniqueMsgId String A unique ID for the response message. This is logged and used to track the specific transaction for troubleshooting purposes.
extendedOnlineDetails Object An object containing additional information. See details in the table below.

Extended online details:

Parameters DataType Description
lastSuccessfulLogin DateTime (epoch) Last time this user auccessfully authenticated  (in UNIX epoch format).
deviceOSVersion String OS version of the device.
deviceFp String PingID device fingerprint.
performedFormType String Which form type was used for authentication, value will be "SLIDER".
gracePeriod DateTime (epoch) When the grace period to allow bypassing PingID authentication expires (in UNIX epoch format).
adminHelp String Descriptive prompt the application can display to direct the end user for help.
deviceType String Device type (such as, Android, iPhone).
gpsLocation Object GPS location of the device at authentication.

 

Offline authentication is performed when one of the following conditions applies:

  • The user has configured a preference for authentication by SMS, voice message, email, YubiKey or FIDO security key.
  • The user’s device is inaccessible over the internet.
  • The user’s device cannot receive push notifications (due to a firewall or other local restrictions).

Before the AuthenticateOffline operation can be performed, the user must manually enter a one-time password which is generated by the PingID mobile app, by a YubiKey or FIDO security key, or sent via SMS, voice message or email. Once the user has entered the OTP, the service provider application calls AuthenticateOffline, while passing the OTP value to PingID.

In the case of a FIDO security key authentication flow, activation of the WebAuthnStartAuth API and the call to the browser’s navigator.credentials.get function are required prior to the AuthenticateOffline API activation. WebAuthnStartAuth and the navigator.credentials.get function generate values which are used as AuthenticateOffline API input parameters. The AuthenticateOffline API completes the FIDO security key authentication flow. For further information, refer to Example : PingID FIDO security key.

This is the AuthenticateOffline URL:

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

 

Request Body Parameters

Example reqBody object in the API payload:

"reqHeader": { ... },
"reqBody": {
  "spAlias": "web",
  "userName": "marcher",
  "otp": "111111",
  "sessionId": "abcd123",
  "clientData": "Session data echoed back to the requestor"
}

The parameters included in the reqBody object are:

Parameter DataType Description
otp String

The “otp” parameter value may be one of the following, depending on the authenticating device:

  • Mobile, SMS, voice or  email devices: The value of the one-time passcode that the user entered.
  • YubiKey which features OTP support: The value of the encrypted one-time passcode generated by the YuibiKey.
  • FIDO security key: The authentication assertion response from the authenticator.
sessionId String The sessionId value returned in the AuthenticateOnline 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.
spAlias String Set this parameter's value to "web" to indicate a web authentication.
userName String The user’s PingID username.
formParameters Map
<String, String>

Optional key/value pairs, unless the authenticating device is a FIDO security key.

Provide the following mandatory parameters when the authenticating device is a FIDO security key:

  • origin: The scheme and domain of the URL that the user wants to access.
  • rpId: The domain of the URL that the user wants to access. The rpId that is used for pairing must be used for authentication.
  • sessionId: The WebAuthn session ID.

If any of the mandatory parameters are not valid, an internal server error is returned.

Refer to Example : PingID FIDO security key.


Response Body Parameters

Example response body:

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

The parameters included in the responseBody object are:

Parameters DataType Description
clientData String The value sent in the request’s clientData field.
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.
sessionId String The sessionId value sent in the request.

 

The WebAuthnStartAuth API is an integral step in the FIDO security key authentication flow. On the basis of input parameters provided as outputs from the StartAuth API, the WebAuthnStartAuth 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.get function, which will return the public key credentials. For further information, refer to Example : PingID FIDO security key.

This is the AuthenticateOnline URL:

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

 

Request Body Parameters

Example reqBody object in the API payload:

"reqHeader": { ... },
"reqBody": {
  "rpId": "pingone.com",
  "userName": "fidouser1",
  "deviceUuid": "0f0eaf16-bc75-b440-0f0e-af16bc75b440"
}

The parameters included in the reqBody object are:

Parameters DataType Description
rpId String Domain of the service provider. The rpId that is used for pairing must be used for authentication.
userName String The user’s PingID username.
deviceUuid String The FIDO security key’s unique device ID.

 

Response Body Parameters

Example response body:

{
  "publicKeyCredentialOptions": "{\"challenge\":[-105,12,-73,3,-45,-70,59,120,30,100,-65,1,-119,49,61,126,-64,112,-29,-62,-113,87,51,70,-43,20,-8,-104,70,-8,-26,81],\"timeout\":120000,\"rpId\":\"pingone.com\",\"allowCredentials\":[{\"type\":\"public-key\",\"id\":[-108,35,43,99,-118,85,-65,-100,-121,97,-48,-100,-94,67,-35,15,-29,20,-3,-115,13,26,36,14,118,43,34,-53,-6,-59,-124,44,-58,60,-3,3,-19,-91,75,-46,112,-20,-109,121,-111,-80,-17,-64,0,63,-9,65,-87,-105,87,22,33,91,-107,-63,43,29,58,-20]}],\"userVerification\":\"preferred\"}",
  "sessionId": "a6b4ee5f-fbe0-403b-838a-4bb6b0520485",
  "errorId": 200,
  "errorMsg": "",
  "uniqueMsgId": "webs_-uD8DyzzMPORJWbF-M3PZxW1wrSAF-swE3pMjwGlj8k",
  "clientData": null
}

The parameters included in the response body object are:

Parameters 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 authentication.

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.