PingID Authentication API


The PingID 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 (via the PingID app, email, SMS, voice, YubiKey, FIDO security key or OATH token). 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.

Start Authentication Workflow

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, YubiKey, FIDO security key or OATH token.

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.

Cancel Authentication Workflow

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.

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 Workflow

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.

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 Workflow

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, FIDO security key or OATH token.
  • 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.

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.

FIDO authentication workflow

When a user wants to authenticate using a FIDO2 or U2F security key, or a FIDO2 supported biometrics device, 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 for FIDO security key, or errorID 30013 for FIDO biometrics) 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 authentication of the FIDO security key or FIDO supported biometrics device.
For further information, refer to:

The YubiKey Authentication Device

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.

StartAuthentication

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",
  "enforcePolicy": "true",
  "ipAddr": "103.25.46.58",
  "application": "google.com",
  "cookie": "cookie_webs_2tZY-sjFNLYDsGyb3yPKUkUn8PTPuzyjrsQeLt_7fHM",
  "reqDevFP": "\{User-Agent=\"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/75.0.3770.100 Safari/537.36\"}",
  "memberOf": ["CN=aliceA,OU=US,OU=Americas,DC=net","CN=bobB,OU=EU,OU=England,DC=net"],
    "formParameters": {
        "isWebAuthnSupportedByBrowser": "true",
        "isWebAuthnPlatformAuthenticatorAvailable": "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.
enforcePolicy Boolean Set this parameter to “true” to activate policy evaluation.
Default: false.
ipAddr String The requesting device’s IP address.
Required in cases where enforcePolicy = “true” and IP address policies are evaluated.
When the ipAddr parameter has a value, it is validated to check that the value is in IP address format.
application String The requested application’s ID, as defined in the application list in the Policy section of the PingID admin portal.
Required in cases where enforcePolicy = “true” and application policies are evaluated.
Maximum length: 500 characters.
cookie String The PingID cookie received in the previous authentication response, in cases where enforcePolicy = “true”.
On completion of a successful authentication using AuthenticateOnline, the cookie parameter returned in the AuthenticateOnline response is populated with the latest authentication transaction’s data. For policy evaluation purposes, save this parameter and use it in the user’s next authentication request.
Maximum length: 5000 characters
reqDevFP String The requesting device’s user agent.
Required in cases where enforcePolicy = “true” and the device’s attributes are evaluated.
Maximum length: 50000 characters
memberOf json array List of users and groups.
Required in cases where enforcePolicy = “true” and group policies are evaluated.
Maximum items: 1000.
formParameters Map
<String, String>
Optional key/value pairs.
  • isWebAuthnSupportedByBrowser
    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, it will fail 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).
    If no other devices exist for this user, it will return HTTP status 400 with error code 20570 (WEBAUTHN_NOT_SUPPORTED_BY_BROWSER).
    Refer to Example : PingID FIDO security key.
  • isWebAuthnPlatformAuthenticatorAvailable
    The “isWebAuthnPlatformAuthenticatorAvailable” key has a default value of “true”, making the assumption that the client browser supports FIDO biometrics. In the case of a FIDO biometrics flow, the client browser’s ability to support FIDO biometrics should be checked before activating this API.
    If the browser does not support FIDO biometrics, it will fail.
    When “isWebAuthnPlatformAuthenticatorAvailable” is “false”, FIDO biometric 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 biometrics.
    If no other devices exist for this user, it will return HTTP status 400 with error code 20570 (WEBAUTHN_NOT_SUPPORTED_BY_BROWSER).

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)
  • 30013 – Offline authentication (FIDO biometrics)
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.
displayID String The ID of the device, according to the device’s type. For example:
  • Device model (Mobile device)
  • Serial number (YubiKey)
  • Country code and phone number (SMS and Voice)
  • Email address (Email)
  • Client browser platform (FIDO biometrics)
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).

CancelAuthentication

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:

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

AuthenticateOnline

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",
  "enforcePolicy": "true",
  "ipAddr": "103.25.46.58",
  "application": "google.com",
  "cookie": "cookie_webs_2tZY-sjFNLYDsGyb3yPKUkUn8PTPuzyjrsQeLt_7fHM",
  "reqDevFP": "\{User-Agent=\"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/75.0.3770.100 Safari/537.36\"}",
  "memberOf": ["CN=aliceA,OU=US,OU=Americas,DC=net","CN=bobB,OU=EU,OU=England,DC=net"]
}

The parameters included in the reqBody object are:

Parameters 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)
enforcePolicy Boolean Set this parameter to “true” to activate policy evaluation.
Default: false.
ipAddr String The requesting device’s IP address.
Required in cases where enforcePolicy = “true” and IP address policies are evaluated.
When the ipAddr parameter has a value, it is validated to check that the value is in IP address format.
application String The requested application’s ID, as defined in the application list in the Policy section of the PingID admin portal.
Required in cases where enforcePolicy = “true” and application policies are evaluated.
Maximum length: 500 characters.
cookie String The PingID cookie received in the previous authentication response, in cases where enforcePolicy = “true”.
On completion of a successful authentication using AuthenticateOnline, the cookie parameter returned in the AuthenticateOnline response is populated with the latest authentication transaction’s data. For policy evaluation purposes, save this parameter and use it in the user’s next authentication request.
Maximum length: 5000 characters
reqDevFP String The requesting device’s user agent.
Required in cases where enforcePolicy = “true” and the device’s attributes are evaluated.
Maximum length: 50000 characters
memberOf json array List of users and groups.
Required in cases where enforcePolicy = “true” and group policies are evaluated.
Maximum items: 1000.
formParameters Object Additional parameters used to customize the authentication. See table below.

The formParameters object can contain the following parameters:

Parameters 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",
 "cookie": "cookie_webs_2tZY-sjFNLYDsGyb3yPKUkUn8PTPuzyjrsQeLt_7fHM"
}

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.
cookie String A new PingID cookie received in cases where enforcePolicy = “true”.
For policy evaluation purposes, save the updated value of the cookie parameter, and use it in the user’s next authentication request.
Maximum length: 5000 characters

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.

AuthenticateOffline

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, FIDO security key or OATH token.
  • 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 FIDO biometrics, 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 or FIDO biometrics 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 or FIDO biometrics authentication flow. For further information, refer to:

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:

Parameters 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.
  • authWebauthnSessionId:
    The WebAuthn session ID.
If any of the mandatory parameters are not valid, an internal server error is returned.
Refer to:

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.

WebAuthnStartAuth (FIDO security key)

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",
  "webauthnType: "WebAuthn"
}

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.
Mandatory, for FIDO security keys.
webauthnType String Set to WebAuthn for authentication of a FIDO security key.

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 WebAuthn session ID.
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.

WebAuthnStartAuth (FIDO biometrics)

The WebAuthnStartAuth API is an integral step in the FIDO biometrics 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 biometrics.

This is the AuthenticateOnline URL:

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

Request Body Parameters

Example reqBody object in the API payload:

"reqBody": {
    "rpId": "pingone.com",
    "userName": "fidouser1",
    "deviceUuid": "16e3f7de-f6af-9cf0-16e3-f7def6af9cf0",
    "webauthnType": "webauthn_platform"
  }

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 biometric platform’s unique device ID.
Optional, for FIDO biometrics.
If the deviceUuid parameter is not provided in the request, the webauthnType parameter must be set to “webauthn_platform”, and the response will return all permitted FIDO biometric devices in the allowCredentials array for the user.
webauthnType String Set to webauthn_platform for authentication of a FIDO2 supported biometric platform.

Response Body Parameters

Example response body:

{
  "responseBody": {
    "clientData": null,
    "errorId": 200,
    "errorMsg": "",
    "sessionId": "abec8ed8-13fc-4c49-a157-9db1ffaf74f4",
    "publicKeyCredentialOptions": "{\"challenge\":[-22,-63,-8,98,-35,-54,92,-25,-13,-76,-51,86,-120,63,-11,89,45,-20,86,-63,114,-65,26,34,13,-84,-4,112,-110,66,-12,-31],\"timeout\":120000,\"rpId\":\"pingone.com\",\"allowCredentials\":[{\"type\":\"public-key\",\"id\":[11,35,-62,-60,-118,-97,126,80,17,121,-30,-50,122,8,-42,-87,-123,56,29,106,90,68,57,-99,-108,13,45,93,11,-13,80,54],\"transports\":[\"internal\"]}],\"userVerification\":\"preferred\"}",
    "uniqueMsgId": "webs_ohi_slDY5XVgotezgpFMNlCIW7NtLvLrWxVo8gFCe14AXw4"
  }
}

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 FIDO biometrics.
sessionId String The WebAuthn session ID.
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.