Platform APIs
More PingIdentity APIs

Authentication API

Relative path:

/accounts/{account_id}/applications/{application_id}/users/{username}/authentications/{authentication_id}

This is a central API, used for authentication of users and their devices.

All requests require authorization of the server. For further details, refer to Signatures in PingID SDK.

Authentication representation

Parameter Name Type Description
id String The session id returned from a call.
authenticationType enum

Type of authentication mechanism to use.

At the moment, only one valid value is supported = AUTHENTICATE.

This is a required parameter.
payload String A string generated by PingID SDK mobile component.

Optional.
deviceId String

Specify a device with which to authenticate.

Optional, if the application is in “default to primary” mode, or if a user has only one trusted device. Otherwise, it is required

It also receives the value returned from the call.
ipAddress String The IP address of a user device sent in a POST method to the PingID SDK server.

Optional.
userAgent String The browser (eg. Chrome, Firefox, etc.), or developer defined origin of the call.

Optional.
offlineOTP String The OTP entered by the user.
status enum

The status returned by the call.

Valid values:

  • OTP

    The user should enter a one time passcode.

    The PATCH method should be called.

  • REJECTED

    The authentication of the user or device has been rejected (the device has been previously blocked from access).

  • APPROVED

    The authentication of the user or device has been approved.

  • IN_PROGRESS

    The authentication of the user is in progress. The customer server application should read the authentication resource again.

  • TIMEOUT

    The maximum permitted time for authentication of the user has lapsed, but the user’s device was unreachable, or the user did not react.

  • LOCKED

    The user is locked for a period of time, since they tried to authenticate offline and entered a wrong OTP for the maximum possible attempts.

  • OTP_IS_BLOCKED

    The authentication of the user ended, and the application’s configuration doesn’t allow OTP fallback.

  • INVALID_OTP

    The user entered the wrong OTP, and is permitted to retry.

    The PATCH method should be called.

  • CANCELED

    The user canceled their authentication attempt before it completed.

  • SELECT_DEVICE

    Device selection prompt. this may mean one of the following:

    • The application’s configuration is set to Device selection mode.

    • The application’s configuration is set to Default to primary. The user has more than one trusted device, but does not have a primary device.

      In this case, the customer server’s application should call the POST method again and provide the deviceId.

      To retrieve the value of deviceId, the customer server's application may use one of the following:
      • The GET method of the Users API, with the expand=devices query parameter. Refer to Users API for details.
      • The GET method of the Users Devices API. Refer to User Devices API for details.

  • IGNORED_DEVICE

    The user tried to authenticate, from a device that was configured as IGNORED. PingID SDK ignores pairing or authenticating requests from this device.

  • BYPASSED_DEVICE

    The admin has configured this device to gain access and bypass the MFA requirement.
device Device The authenticating device. This value is returned from the call.

May be null.
accessingDevice Device The accessing device. This value is returned from the call.

May be null.
requiredLevel enum

The level of authentication required by the configuration of the application. This value is returned from the call.

Valid values:

  • MOBILE_PAYLOAD

    The customer server application will receive this value when the attribute USE_PUSH_FOR_EXTRA_VERIFICATION is disabled.

  • PUSH

    The customer server application will receive this value when the attribute USE_PUSH_FOR_EXTRA_VERIFICATION is enabled.
level enum

The level of authentication, returned from the call. This is submitted by the PingID SDK server.

Valid values:

  • NONE (mobile flow)

    The initial value when a user tries to get access from a seen device or from a device without the PingID SDK customer component.

  • MOBILE_PAYLOAD (mobile flow)

    The PingID SDK server authenticated the trusted device of the user via the payload of the PingID SDK customer component.

  • OTP (web flow)

    The PingID SDK server authenticated the user via an OTP.

  • PUSH (mobile and web flow)

    The PingID SDK server sent a push notification to an authentication device of the user.
pushMessageTitle String The text of the title of the notification message.

Optional.

If both pushMessageTitle and pushMessageBody are null, the server will send the default title (notification.title) and body (notification.message). Either both the pushMessageTitle and pushMessageBody should be provided, or neither should be provided. If only one is provided, an error will be returned.
pushMessageBody String The text of the body of the notification message.

Optional.

If both pushMessageTitle and pushMessageBody are null, the server will send the default title (notification.title) and body (notification.message). Either both the pushMessageTitle and pushMessageBody should be provided, or neither should be provided. If only one is provided, an error will be returned.
pushCategory String Optional: User-defined category for push messages.
Only English letters, digits, "-" and "_" are allowed, up to a maximum length of 64 characters.
clientContext String Optional: Data that the customer server may transfer to the customer app. The PingID SDK transfers this data as is.
smsMessage String The SMS message which is sent in order to authenticate a user.
  • Mandatory, when the authenticating device is SMS.
  • Used only if the authenticating device is SMS.

Refer to Authenticate with SMS for details and examples of smsMessage and smsSender usage.
smsSender String

The sender ID of the SMS message. This parameter is optional, and used only if the authenticating device is SMS.

If the sender ID is specified:

  • Only numbers, English characters and spaces are allowed.

  • Length may be up to a maximum of 11 characters.

If the sender field is empty, the SMS sender will be an arbitrary PingID phone number, except for India. If the SMS recipient is located in India, the sender will appear as “PingID”, which is the required registered sender ID in India.

Refer to Authenticate with SMS for details and examples of smsMessage and smsSender usage.
reason enum Failure reason in authentication POST or GET operations.
Possible values:
  • DENIED_BY_USER
  • BLOCKED_BY_USER
  • CANCELED_BY_USER
  • DEVICE_BLOCKED
  • DEVICE_ROOTED
approvedDeviceState String The state of an approved untrusted device, in scenarios where an authentication request from the untrusted mobile app is approved by the user using a different, trusted device.
Possible values for the state, that the user chooses for the untrusted device:
  • APPROVED_FOR_REGISTRATION
    The user permits registration of the untrusted device. The device can now begin the registration process.
  • IGNORED
    The user allows this device access, marking the device to be ignored for registration or authenticating requests for a period of time.
  • ONE_TIME_ACCESS_ALLOWED
    The user allows this device permission for a single access, without registration.
The value of approvedDeviceState is null for all other scenarios.

Available REST operations

HTTP Method Description
POST Start a new authentication.
GET Retrieve an authentication.
PUT Update an authentication.
DELETE Cancel an authentication.

Start a new authentication (POST)

To start a new authentication, the customer server will initiate a POST request to the Authentication Endpoint in the PingID SDK service. To execute an authentication, a user should be active in the PingID SDK service. This type of operation is asynchronous. The final result of the authentication process may be calculated immediately, or it may take some time. There is a status field in the Authentication Resource. Depending on the returned value of the status, the customer server application may decide how to handle the authentication request of the user, or continue to poll the Authentication Resource.

Relative Path

/accounts/{accountId}/applications/{applicationId}/users/{username}/authentications

Parameters

Parameter Name Type Description
accountId String The ID of the PingID SDK tenant.
applicationId String The ID of the PingID SDK client application.
username String The user's unique name in PingID SDK, per tenant.

Request Body

Parameter Name Value Description
payload String The string generated by the PingID SDK component. Optional.
deviceId String The specific device with which to authenticate.

Optional.

This parameter should be specified in the following cases:
  • In device selection mode.
  • When the user has more than one trusted device.
ipAddress String IP address of the user’s client (mobile or web).. Optional.
userAgent String Client User Agent (mobile or web) Optional.
pushMessageTitle String The text of the title of the notification message. Optional.
pushMessageBody String The text of the body of the notification message. Optional.
clientContext String Data that the customer server may transfer to the customer app. The PingID SDK transfers this data as is. Optional.
smsMessage String (Relevant when the authenticating device is SMS.) The SMS message which is sent in order to authenticate a user.
smsSender String (Relevant when the authenticating device is SMS.) The ID of the sender of the SMS message.
Other fields are not relevant for the POST request.

Following is an example of a web authentication. As there is no PingID SDK customer app component in this example, the body of the request doesn’t contain a payload.

  • Start a new authentication: (POST) request body example:

    curl -X POST \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: PINGID-HMAC=<JWT>' -d '{"authenticationType":"AUTHENTICATE" }' 'https://sdk.pingid.com/pingid/v1/accounts/e17f898d-3577-490d-baa7-64ceecf6b8a5/applications/49b9ed37-31ce-488f-9c44-1fe1ed95f756/users/john.galt/authentications'

  • Start a new authentication: (POST) response body example:

    {
  "self": {
    "href": "https://sdk.pingid.com/pingid/v1/accounts/e17f898d-3577-490d-baa7-64ceecf6b8a5/applications/49b9ed37-31ce-488f-9c44-1fe1ed95f756/users/john.galt/authentications/webs_d3efe03a-53c3-4f71-899a-a3c815284103"
  },
  "user": {
    "href": "https://sdk.pingid.com/pingid/v1/accounts/e17f898d-3577-490d-baa7-64ceecf6b8a5/users/john.galt"
  },
  "account": {
    "href": "https://sdk.pingid.com/pingid/v1/accounts/e17f898d-3577-490d-baa7-64ceecf6b8a5"
  },
  "authenticationId": "webs_d3efe03a-53c3-4f71-899a-a3c815284103",
  "deviceId": "128bd7a1-6b6a-4d37-128b-d7a16b6a4d37",
  "status": "IN_PROGRESS",
  "reason": null,
  "device": {
    "deviceType": "iPhone",
    "id": "128bd7a1-6b6a-4d37-128b-d7a16b6a4d37",
    "deviceFingerprint": "9Pzk1Y0YQBj5XwKcSBWm",
    "deviceName": "iPhone 5S",
    "deviceRole": null,
    "enrollmentTime": null,
    "applicationId": "49b9ed37-31ce-488f-9c44-1fe1ed95f756",
    "bypassExpiration": null,
    "bypassed": false,
    "rooted": null
  },
  "requiredLevel": "PUSH",
  "level": "NONE",
  "payload": ""
}

Retrieve an authentication (GET)

To retrieve an authentication resource, the customer server application should call the GET method of this endpoint.

Relative Path

/accounts/{accountId}/applications/{applicationId}/users/{username}/authentications/{authenticationId}

Parameters

Parameter Name Type Description
account_id String The ID of the PingID SDK tenant.
applicationId String The ID of the PingID SDK client application.
username String The user’s unique name in PingID SDK, per tenant.
authenticationId String The value of the ID of the authentication request returned in the POST response.

Following is an example of a web authentication. There is no PingID SDK mobile component .

  • Retrieve an authentication: (GET) request body example:

    curl -X GET \
 --header 'Accept: application/json' \
 --header 'Authorization: PINGID-HMAC=<JWT>' \
'https://sdk.pingid.com/pingid/v1/accounts/e17f898d-3577-490d-baa7-64ceecf6b8a5/applications/49b9ed37-31ce-488f-9c44-1fe1ed95f756/users/john.galt/authentications/webs_badaca9e-cfba-446f-99a0-03e6e7bc1706'

  • Retrieve an authentication: (GET) response body example:

    {
  "application": {
    "href": "https://sdk.pingid.com/pingid/v1/accounts/e17f898d-3577-490d-baa7-64ceecf6b8a5/applications/49b9ed37-31ce-488f-9c44-1fe1ed95f756"
  },
  "self": {
    "href": "https://sdk.pingid.com/pingid/v1/accounts/e17f898d-3577-490d-baa7-64ceecf6b8a5/applications/49b9ed37-31ce-488f-9c44-1fe1ed95f756/users/john.galt/authentications/webs_badaca9e-cfba-446f-99a0-03e6e7bc1706"
  },
  "user": {
    "href": "https://sdk.pingid.com/pingid/v1/accounts/e17f898d-3577-490d-baa7-64ceecf6b8a5/users/john.galt"
  },
  "account": {
    "href": "https://sdk.pingid.com/pingid/v1/accounts/e17f898d-3577-490d-baa7-64ceecf6b8a5"
  },
  "id": "webs_badaca9e-cfba-446f-99a0-03e6e7bc1706",
  "deviceId": "2c532ca0-cd9f-4451-2c53-2ca0cd9f4451",
  "status": "APPROVED",
  "reason": null,
  "device": {
    "deviceType": "iPhone",
    "id": "2c532ca0-cd9f-4451-2c53-2ca0cd9f4451",
    "deviceFingerprint": "H5SokIpRMUiS3ETOAsSI",
    "deviceName": "iPhone 5S",
    "deviceRole": "primary",
    "enrollmentTime": 1490106758323,
    "applicationId": "49b9ed37-31ce-488f-9c44-1fe1ed95f756",
    "bypassExpiration": null,
    "bypassed": false,
    "rooted": null
  },
  "requiredLevel": "PUSH",
  "level": "PUSH",
  "payload": ""
}

Relative Path

/accounts/\{account_id}/applications/{application_id}/users/{username}/authentications/{authentication_id}

Parameters

Parameter Name Type Description
account_id String The ID of the PingID SDK tenant.
application_id String The ID of the PingID SDK client application.
username String The user's unique name in PingID SDK, per tenant.
authentication_id String The authenticationId value returned in the POST response

Request Body

Parameter Name Type Description
offlineOTP String The OTP entered by the user.
payload String The string generated by PingID SDK mobile component.

Optional.

  • Update the authentication resource: (PATCH) request example:

    curl -X PATCH \
 --header 'Content-Type: application/json' \
 --header 'Accept: application/json' \
 --header 'Authorization: PINGID-HMAC=<JWT>' \
 -d '{ \ 
   "operations":  [ \ 
     { \ 
            "op": "add", \ 
            "path": "/offlineOTP", \ 
             "value": "481547" \
      } \ 
  ] \ 
 }' 'https://sdk.pingid.com/pingid/v1/accounts/e17f898d-3577-490d-baa7-64ceecf6b8a5/applications/49b9ed37-31ce-488f-9c44-1fe1ed95f756/users/john.galt/authentications/webs_94b00632-956a-4015-8d87-6046bb5f04f5'

  • Update the authentication resource: (PATCH) response example:

    {
  "self": {
    "href": "https://sdk.pingid.com/pingid/v1/accounts/e17f898d-3577-490d-baa7-64ceecf6b8a5/applications/49b9ed37-31ce-488f-9c44-1fe1ed95f756/users/john.galt/authentications/webs_94b00632-956a-4015-8d87-6046bb5f04f5"
  },
  "user": {
    "href": "https://sdk.pingid.com/pingid/v1/accounts/e17f898d-3577-490d-baa7-64ceecf6b8a5/users/john.galt"
  },
  "account": {
    "href": "https://sdk.pingid.com/pingid/v1/accounts/e17f898d-3577-490d-baa7-64ceecf6b8a5"
  },
  "id": "webs_94b00632-956a-4015-8d87-6046bb5f04f5",
  "deviceId": "2c532ca0-cd9f-4451-2c53-2ca0cd9f4451",
  "status": "APPROVED",
  "requiredLevel": "PUSH",
  "level": "OTP",
  "payload": ""
}

Update the authentication resource: (PUT)

This method is performed when one of the following conditions apply:

  • 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.
  • The user’s device is SMS, voice or email.

In these cases, the user must manually enter an OTP, which is generated by the PingID SDK component in the case of a mobile application, or, depending on the type of user device, sent to the user in an SMS message, or in a voice call, or in an email.

Relative Path

/accounts/{account_id}/applications/{application_id}/users/{username}/authentications/{authentication_id}/otp

Parameters

Parameter Name Type Description
account_id String The ID of the PingID SDK tenant.
application_id String The ID of the PingID SDK client application.
username String The user's unique name in PingID SDK, per tenant.
authentication_id String The authenticationId value returned in the POST response.

Request body structure

Use the following request body structure:

request body
{
"otp": "123456",
"payload": "<payload string>"
}

Note that the payload parameter must be provided only if the request originated from a mobile SDK component, otherwise it should not be provided.

Request parameters

Parameter Name Type Description
otp String The OTP entered by the user.
payload String The string generated by PingID SDK mobile component.

Optional.
  • Update the authentication resource: (PUT) request example:
curl -X PUT \
 --header 'Content-Type: application/json' \
 --header 'Accept: application/json' \
 --header 'Authorization: PINGID-HMAC=<JWT>' \
 -d '{ \ "otp": "363451"}' 'https://sdk.pingid.com/pingid/v1/accounts/e17f898d-3577-490d-baa7-64ceecf6b8a5/applications/49b9ed37-31ce-488f-9c44-1fe1ed95f756/users/john.galt/authentications/webs_94b00632-956a-4015-8d87-6046bb5f04f5/otp'
  • Update the authentication resource: (PUT) response example:
{
  "self": {
    "href": "https://sdk.pingid.com/pingid/v1/accounts/e17f898d-3577-490d-baa7-64ceecf6b8a5/applications/49b9ed37-31ce-488f-9c44-1fe1ed95f756/users/john.galt/authentications/webs_94b00632-956a-4015-8d87-6046bb5f04f5"
  },
  "user": {
    "href": "https://sdk.pingid.com/pingid/v1/accounts/e17f898d-3577-490d-baa7-64ceecf6b8a5/users/john.galt"
  },
  "account": {
    "href": "https://sdk.pingid.com/pingid/v1/accounts/e17f898d-3577-490d-baa7-64ceecf6b8a5"
  },
  "id": "webs_94b00632-956a-4015-8d87-6046bb5f04f5",
  "deviceId": "2c532ca0-cd9f-4451-2c53-2ca0cd9f4451",
  "status": "APPROVED",
  "requiredLevel": "PUSH",
  "level": "OTP",
  "payload": ""
}

Cancel the authentication resource: (DELETE)

The DELETE authentication method is used when a user cancels an authentication in progress .

Relative Path

/accounts/{account_id}/applications/{application_id}/users/{username}/authentications/{authentication_id}

Parameters

Parameter Name Type Description
account_id String The ID of the PingID SDK tenant.
application_id String The ID of the PingID SDK client application.
username String The user's unique name in PingID SDK, per tenant.
authentication_id String The authenticationId value returned in the POST response.

  • Cancel the authentication resource: (DELETE) request example:

    curl -X DELETE \
 --header 'Authorization: PINGID-HMAC=<JWT>' \
 --header 'Accept: application/json' \
'https://sdk.pingid.com/pingid/v1/accounts/e17f898d-3577-490d-baa7-64ceecf6b8a5/applications/49b9ed37-31ce-488f-9c44-1fe1ed95f756/users/john.galt/authentications/webs_2ddb0d4c-f571-4092-90cc-7cf2270145ae'

  • Cancel the authentication resource: (DELETE) response example:

    no content