Platform APIs
More PingIdentity APIs

Application Attributes API

Use this API to manage PingID SDK application configurations.

PingID SDK Application configurations can also be managed in the admin web console. See Update a PingID SDK app’s configuration.

Application attribute representation

Parameter Name Type Description
name String The application attribute name.
value String The application attribute value.

Available Application Attributes

Attribute name Description Allowed values
multiple_device_selection_mode Whether users are prompted for authentication with their primary device, or prompted to select a device.
If the user has only one trusted device, irrespective of whether it is a primary device or not, the Authentication API will use it as the authentication device.
  • false (default):
    Prompt for authentication with primary device.
    If the user doesn’t have a primary device and has multiple trusted devices, the Authentication API will return the SELECT_DEVICE status.
  • true:
    Prompt users to receive a prompt on each authentication to choose the device to use, when they have more than one trusted device.
max_allowed_devices_for_user You can determine the maximum number of devices that each user can have. Users will not be able to add more devices for authentication than the maximum number that is configured.
  • Minumum: 1
  • Maximum: 15
  • Default: 5
otp_fallback_enabled When there’s a mobile app response timeout or if the device is pushless, determine whether the user is presented with the OTP input screen and can use OTP for authentication.
  • false (default):
    Disable OTP fallback.
  • true:
    Enable OTP fallback.
max_allowed_mobile_app_otp_attempts The maximum number of times that the OTP entry can fail for a user, before their device is blocked.
  • Minumum: 1
  • Maximum: 7
  • Default: 3
mobile_app_lock_otp_duration The amount of time a user’s device will be blocked if they exceed the maximum number of passcode failures. The duration may be set in units of minutes or seconds. Regular expression in the form
\\d+[sm]?
For example:
2m for 2 minutes
125s for 125 seconds
  • Minumum: 2 minutes
  • Maximum: 30 minutes
  • Default: 2 minutes
pairing_key_expiration The duration of validity in minutes, hours or days for a manual pairing key, before it expires. Regular expression in the form
\\d+[mhd]?
For example:
30m for 30 minutes
4h for 4 hours
2d for 2 days
  • Maximum: 31 days
  • Default: 48 hours
application_scheme_uri URI prefix (URL or URI scheme), to which a user will be directed after successfully scanning the QR code or clicking the deep link. The URL PREFIX must conform to the following requirements:
  • A string of up to 30 characters starting with an English character (a-z).
  • Subsequent characters may comprise only English alphanumerics (a-z, 0-9), the plus (+), minus (-) or dot(.) characters.
use_push_for_extra_verification Whether to use the Apple or Android push servers to provide extra verification during device authorization.
  • false (default):
    Disable extra verification.
  • true:
    Enable extra verification.
skip_push_for_authentication_token_extra_verification Whether to use the Apple or Android push server to provide extra verification during QR code based authorization.
  • false (default):
    Enable extra verification.
  • true:
    Disable extra verification.
root_detection_enforce_policy Whether to check the integrity of mobile devices and detect whether they are rooted or jailbroken.
  • false (default):
    Ignore rooted and jailbroken device detection.
  • true:
    Check the integrity of mobile devices and detect whether they are rooted or jailbroken.
root_detection_ios The PingID SDK integrity check solution uses its proprietary algorithm to determine if an iOS mobile device is jailbroken.
Note: root_detection_enforce_policy must be true for this value to take effect.
  • ENABLED (default):
    Check the integrity of iOS devices and to detect jailbroken iOS devices.
  • DISABLED:
    Ignore jailbreak detection for iOS devices.
root_detection_android The PingID SDK root detection solution utilizes Google’s SafetyNet attestation API to determine the integrity of Android mobile devices.
See Google’s SaftyNet potential integrity verdicts documentation for further information about SafetyNet integrity levels.
Note: root_detection_enforce_policy must be true for this value to take effect.
  • DISABLED:
    Ignore root detection for Android devices.
  • BASIC INTEGRITY:
    Applies SafetyNet Basic Integrity for the basic integrity check.
  • CTS (default):
    SafetyNet CTS to return a verdict for the more stringent Compatibility Test Suite standard.
root_detection_caching_interval Root detection cache duration.
Since SafetyNet is an external service provided by Google, every attestation request entails a certain time tradeoff.
You can choose to cache successful SafetyNet calls for a predefined duration, between a minimum of 1 minute and a maximum of 48 hours.
Note: root_detection_enforce_policy must be true for this value to take effect.		 Regular expression in the form
\\d+[hm]?
For example:
5m for 5 minutes
6h for 6 hours
  • Minumum: 1 minute
  • Maximum: 48 hours
  • Default: 24 hours
root_detection_safetynet_unavailable Determine if PingID SDK should consider a failed SafetyNet response as a rooted or non-rooted device. Following an Android device’s pairing or authentication request, determine whether the request will be granted, if SafetyNet doesn’t respond in time, or if Google Play is not installed on the device.
Note: root_detection_enforce_policy must be true for this value to take effect.
  • FAIL (default):
    Deny the Android device’s pairing or authentication request.
  • APPROVE:
    Approve the Android device’s pairing or authentication request.
root_detection_unavailable Determine PingID SDK’s behavior when an authentication or pairing request is missing the required data to determine the requesting device’s integrity.
This could occur in apps using old mobile SDK component versions, or in apps using a new mobile component versions that call the root detection API with a false flag. The APPROVE setting could assist in a gradual rollout of the integrity check to all users.
Following an Android or iOS device’s pairing or authentication request, determine whether the request will be granted, if the rooted or jailbroken status of the device can’t be determined.
Note: root_detection_enforce_policy must be true for this value to take effect.
  • FAIL (default):
    Deny the device’s pairing or authentication request.
  • APPROVE:
    Approve the device’s pairing or authentication request.
sms_enabled Whether users are permitted authentication via SMS.
Note: Changing this attribute from true to false will unpair users from their SMS authentication devices.
  • false (default):
    Users are not allowed authentication via SMS.
  • true:
    Users are allowed authentication via SMS.
email_enabled Whether users are permitted authentication via email.
Note: Changing this attribute from true to false will unpair users from their email authentication devices.
  • false (default):
    Users are not allowed authentication via email.
  • true:
    Users are allowed authentication via email.
voice_enabled Whether users are permitted authentication via voice.
Note: Changing this attribute from true to false will unpair users from their voice authentication devices.
  • false (default):
    Users are not allowed authentication via voice.
  • true:
    Users are allowed authentication via voice.
use_advanced_otp_conf Whether a single global set of PASSCODE FAILURE LIMIT, BLOCK DURATION and PASSCODE LIFETIME IN MINUTES settings will apply equally to all of the enabled email, SMS and voice methods, or if separate individual configurations will apply for each authentication method.
  • false (default):
    Use global settings for email, voice and SMS.
  • true:
    Use separate individual settings for email, voice and SMS.
global_lock_otp_duration The amount of time a user’s device will be blocked if they exceed the maximum number of passcode failures. The duration can be set in units of minutes or seconds.
This attribute takes effect only when use_advanced_otp_conf is false.		 Regular expression in the form
\\d+[sm]?
For example:
10m for 10 minutes
150s for 150 seconds
  • Minumum: 0 minutes
  • Maximum: 30 minutes
  • Default: 0 minutes (not blocked)
global_otp_lifetime The amount of time an OTP is valid before it expires. The duration may be set in units of minutes.
This attribute takes effect only when use_advanced_otp_conf is false.		 Regular expression in the form
\\d+[m]
For example:
10m for 10 minutes
  • Minumum: 1 minute
  • Maximum: 30 minutes
  • Default: 30 minutes
max_allowed_global_otp_attempts The maximum number of times that the OTP entry can fail for a user’s device, before it is blocked.
The device is locked only if a lock duration is defined.
After reaching the maximum number of failure attempts, the flow ends and exits the OTP entry screen.
This attribute takes effect only when use_advanced_otp_conf is false.
  • Minumum: 1
  • Maximum: 7
  • Default: 3
email_otp_lifetime For email authentication, the amount of time an OTP is valid before it expires. The duration may be set in units of minutes.
This attribute takes effect only when use_advanced_otp_conf is true.		 Regular expression in the form
\\d+[m]
For example:
10m for 10 minutes
  • Minumum: 1 minute
  • Maximum: 30 minutes
  • Default: 30 minutes
email_lock_otp_duration For email authentication, the amount of time a user’s device will be blocked if they exceed the maximum number of passcode failures. The duration can be set in units of minutes or seconds.
This attribute takes effect only when use_advanced_otp_conf is true.		 Regular expression in the form
\\d+[sm]?
For example:
10m for 10 minutes
150s for 150 seconds
  • Minumum: 0 minutes
  • Maximum: 30 minutes
  • Default: 0 minutes (not blocked)
max_allowed_email_otp_attempts For email authentication, the maximum number of times that the OTP entry can fail for a user’s device, before it is blocked.
The device is locked only if a lock duration is defined.
After reaching the maximum number of failure attempts, the flow ends and the exits the OTP entry screen.
This attribute takes effect only when use_advanced_otp_conf is true.
  • Minumum: 1
  • Maximum: 7
  • Default: 3
sms_lock_otp_duration For SMS authentication, the amount of time a user’s device will be blocked if they exceed the maximum number of passcode failures. The duration can be set in units of minutes or seconds.
This attribute takes effect only when use_advanced_otp_conf is true.		 Regular expression in the form
\\d+[sm]?
For example:
10m for 10 minutes
150s for 150 seconds
  • Minumum: 0 minutes
  • Maximum: 30 minutes
  • Default: 0 minutes (not blocked)
sms_otp_lifetime For SMS authentication, the amount of time an OTP is valid before it expires. The duration may be set in units of minutes.
This attribute takes effect only when use_advanced_otp_conf is true.		 Regular expression in the form
\\d+[m]
For example:
10m for 10 minutes
  • Minumum: 1 minute
  • Maximum: 30 minutes
  • Default: 30 minutes
max_allowed_sms_otp_attempts For SMS authentication, the maximum number of times that the OTP entry can fail for a user’s device, before it is blocked.
The device is locked only if a lock duration is defined.
After reaching the maximum number of failure attempts, the flow ends and the exits the OTP entry screen.
This attribute takes effect only when use_advanced_otp_conf is true.
  • Minumum: 1
  • Maximum: 7
  • Default: 3
voice_lock_otp_duration For voice authentication, the amount of time a user’s device will be blocked if they exceed the maximum number of passcode failures. The duration can be set in units of minutes or seconds.
This attribute takes effect only when use_advanced_otp_conf is true.		 Regular expression in the form
\\d+[sm]?
For example:
10m for 10 minutes
150s for 150 seconds
  • Minumum: 0 minutes
  • Maximum: 30 minutes
  • Default: 0 minutes (not blocked)
voice_otp_lifetime For voice authentication, the amount of time an OTP is valid before it expires. The duration may be set in units of minutes.
This attribute takes effect only when use_advanced_otp_conf is true.		 Regular expression in the form
\\d+[m]
For example:
10m for 10 minutes
  • Minumum: 1 minute
  • Maximum: 30 minutes
  • Default: 30 minutes
max_allowed_voice_otp_attempts For voice authentication, the maximum number of times that the OTP entry can fail for a user’s device, before it is blocked.
The device is locked only if a lock duration is defined.
After reaching the maximum number of failure attempts, the flow ends and the exits the OTP entry screen.
This attribute takes effect only when use_advanced_otp_conf is true.
  • Minumum: 1
  • Maximum: 7
  • Default: 3
initial_sms_user_claimed_limit The maximum number of SMS or voice authentication requests a user may receive and respond to each day.
Note: The value is only relevant for a full licence account.
If this value is added for a trial account, it will have no effect.
  • Minimum: 1
  • Maximum: 50
  • Default: 15 for a full license account
initial_sms_user_not_claimed_limit The maximum number of SMS or voice authentication requests a user may receive and not respond to each day.
Note: The value is only relevant for a full licence account.
If this value is added for a trial account, it will have no effect.
  • Minimum: 1
  • Maximum: 50
  • Default: 10 for a full license account
mobile_app_timeout_mode The mode that determines the timeout limits of mobile application authentication requests.
An authentication request’s duration is determined by two configurable measurements:
  • Device Timeout: The amount of time in seconds that a new authentication request notification must reach a user’s mobile device, before timing out.
  • Total Timeout: The total amount of time in seconds that a new authentication request will last, before timing out. This includes the time for Device Timeout, plus the time that the user has to respond to the authentication request.

The timeout mode value is case sensitive, and must be in upper case. Possible modes:
  • DEFAULT: The system’s default timeout values are used for determining the timeout limits of mobile application authentication requests.
    • Device Timeout default: 20 seconds
    • Total Timeout default: 40 seconds.
  • GLOBAL: A custom device timeout value and a custom total timeout value are applied globally to all mobile application authentication requests, irrespective of where the request originated.
  • ADVANCED: Custom device timeout and total timeout values are configured individually for each origin of mobile application authentication requests.
  • DEFAULT (default)
  • GLOBAL
  • ADVANCED
mobile_app_device_timeout The amount of time in seconds that a new authentication request notification must reach the device, before timing out.
It takes effect only if mobile_app_timeout_mode = GLOBAL.
Note: There must be a difference of at least 15 seconds between the mobile_app_device_timeout and mobile_app_total_authentication_timeout values. This might require changing both attributes in the same request.
  • Minimum: 15 seconds
  • Maximum: 40 seconds
  • Default: 20 seconds
mobile_app_total_authentication_timeout The total amount of time in seconds that a new authentication request will last, before timing out.
It takes effect only if mobile_app_timeout_mode = GLOBAL.
Note: There must be a difference of at least 15 seconds between the mobile_app_device_timeout and mobile_app_total_authentication_timeout values. This might require changing both attributes in the same request.
  • Minimum: 40 seconds
  • Maximum: 150 seconds
  • Default: 40 seconds
api_mobile_app_device_timeout The amount of time in seconds that a new authentication request notification must reach the device, before timing out for any API request that does not originate from the CIBA Authenticator (version 1.1.2 and later) or from the PingID SDK Adapter (version 1.8.2 and later).
It takes effect only if mobile_app_timeout_mode = ADVANCED.
Note: There must be a difference of at least 15 seconds between the api_mobile_app_device_timeout and api_mobile_app_total_authentication_timeout values. This might require changing both attributes in the same request.
  • Minimum: 15 seconds
  • Maximum: 40 seconds
  • Default: 20 seconds
api_mobile_app_total_authentication_timeout The total amount of time in seconds that a new authentication request will last, before timing out for any API request that does not originate from the CIBA Authenticator (version 1.1.2 and later) or from the PingID SDK Adapter (version 1.8.2 and later).
It takes effect only if mobile_app_timeout_mode = ADVANCED.
Note: There must be a difference of at least 15 seconds between the api_mobile_app_device_timeout and api_mobile_app_total_authentication_timeout values. This might require changing both attributes in the same request.
  • Minimum: 40 seconds
  • Maximum: 150 seconds
  • Default: 40 seconds
ciba_mobile_app_device_timeout The amount of time in seconds that a new authentication request notification must reach the device, before timing out for any API request that originates from the CIBA Authenticator (version 1.1.2 and later) or from the PingID SDK Adapter (version 1.8.2 and later).
It takes effect only if mobile_app_timeout_mode = ADVANCED.
If the CIBA Authenticator version is earlier than 1.1.2 and mobile_app_timeout_mode = ADVANCED, then the api_mobile_app_device_timeout configuration is used for any authentication request that originates from the CIBA Authenticator.
Note: There must be a difference of at least 15 seconds between the ciba_mobile_app_device_timeout and ciba_mobile_app_total_authentication_timeout values. This might require changing both attributes in the same request.
  • Minimum: 15 seconds
  • Maximum: 40 seconds
  • Default: 20 seconds
ciba_mobile_app_total_authentication_timeout The total amount of time in seconds that a new authentication request will last, before timing out for any API request that originates from the CIBA Authenticator (version 1.1.2 and later).
It takes effect only if mobile_app_timeout_mode = ADVANCED.
If the CIBA Authenticator version is earlier than 1.1.2 and mobile_app_timeout_mode = ADVANCED, then the api_mobile_app_device_timeout configuration is used for any authentication request that originates from the CIBA Authenticator.
Note: There must be a difference of at least 15 seconds between the ciba_mobile_app_device_timeout and ciba_mobile_app_total_authentication_timeout values. This might require changing both attributes in the same request.
  • Minimum: 40 seconds
  • Maximum: 150 seconds
  • Default: 40 seconds
adapter_mobile_app_device_timeout The amount of time in seconds that a new authentication request notification must reach the device, before timing out for any API request that originates from the PingID SDK Adapter (version 1.8.2 and later).
It takes effect only if mobile_app_timeout_mode = ADVANCED.
If the PingID SDK Adapter version is earlier than 1.8.2 and mobile_app_timeout_mode = ADVANCED, then the api_mobile_app_device_timeout configuration is used for any authentication request that originates from the PingID SDK Adapter.
Note: There must be a difference of at least 15 seconds between the adapter_mobile_app_device_timeout and adapter_mobile_app_total_authentication_timeout values. This might require changing both attributes in the same request.
  • Minimum: 15 seconds
  • Maximum: 40 seconds
  • Default: 20 seconds
adapter_mobile_app_total_authentication_timeout The total amount of time in seconds that a new authentication request will last, before timing out for any API request that originates from the PingID SDK Adapter (version 1.8.2 and later).
It takes effect only if mobile_app_timeout_mode = ADVANCED.
If the PingID SDK Adapter version is lower than 1.8.2 and mobile_app_timeout_mode = ADVANCED, then the api_mobile_app_device_timeout configuration is used for any authentication request that originates from the PingID SDK Adapter.
Note: There must be a difference of at least 15 seconds between the adapter_mobile_app_device_timeout and adapter_mobile_app_total_authentication_timeout values. This might require changing both attributes in the same request.
  • Minimum: 40 seconds
  • Maximum: 150 seconds
  • Default: 40 seconds
extra_push_device_timeout The amount of time in seconds that a silent push extra verification request notification must reach the device, before timing out for any request that originates from the mobile app.
It takes effect only if mobile_app_timeout_mode = ADVANCED and use_push_for_extra_verification = true.
  • Minimum: 3 seconds
  • Maximum: 15 seconds
  • Default: 7 seconds
authentication_token_device_timeout The amount of time in seconds that a silent push extra verification request notification must reach the device, before timing out for any request that originates from the mobile app after scanning a QR code.
It takes effect only if mobile_app_timeout_mode = ADVANCED and skip_push_for_authentication_token_extra_verification = false.
  • Minimum: 1 seconds
  • Maximum: 15 seconds
  • Default: 7 seconds

REST operations

HTTP Method Description
POST Create an application attribute.
GET Retrieve all the application attributes for a specific application.
PUT Update application attributes.

Create an application attribute (POST)

Relative Path

/accounts/{accountId}/applications/{applicationId}/attributes

Request Body Structure

{
  "name": "<attribute name>",
  "value": <attribute value>"
}

Create an application attribute request example

curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' -d '{ \ 
   "name": "sms_enabled", \ 
   "value": "true" \ 
 }' 'https://sdk.pingid.com/pingid/v1/accounts/f851a4da-1239-4008-9456-8b93279558f2/applications/cb869bc1-b136-4698-afce-5e6775333bbc/attributes'

Create an application attribute response example

{
  "application": {
    "href": "https://sdk.pingid.com/pingid/v1/accounts/f851a4da-1239-4008-9456-8b93279558f2/applications/cb869bc1-b136-4698-afce-5e6775333bbc"
  },
  "self": {
    "href": "https://sdk.pingid.com/pingid/v1/accounts/f851a4da-1239-4008-9456-8b93279558f2/applications/cb869bc1-b136-4698-afce-5e6775333bbc/attributes"
  },
  "account": {
    "href": "https://sdk.pingid.com/pingid/v1/accounts/f851a4da-1239-4008-9456-8b93279558f2"
  },
  "name": "sms_enabled",
  "value": "true"
}

Update an application’s attributes (PUT)

Relative Path

/accounts/{accountId}/applications/{applicationId}/attributes

Request Body Structure

{
  "attributes": [
    {
      "name": "<attribute name>",
      "value": "<attribute value>"
    }
  ]
}

Update application attributes request example

curl -X PUT --header 'Content-Type: application/json' --header 'Accept: application/json' -d '{ \ 
   "attributes": [ \ 
     { \ 
       "name": "sms_enabled", \ 
       "value": "true" \ 
     }, \ 
     { \ 
       "name": "voice_enabled", \ 
       "value": "true" \ 
     } \ 
   ] \ 
 }' 'https://sdk.pingid.com/pingid/v1/accounts/f851a4da-1239-4008-9456-8b93279558f2/applications/cb869bc1-b136-4698-afce-5e6775333bbc/attributes'

Update application attribute response example

{
  "applicationattributes": [
    {
      "name": "sms_enabled",
      "value": "true"
    },
    {
      "name": "voice_enabled",
      "value": "true"
    }
  ]
}

Get bulk application attributes (GET)

Get all the application attributes for a specific application.

Relative Path

/accounts/{accountId}/applications/{applicationId}/attributes

Get application attributes request example

curl -X GET --header 'Accept: application/json' 'https://sdk.pingid.com/pingid/v1/accounts/f851a4da-1239-4008-9456-8b93279558f2/applications/cb869bc1-b136-4698-afce-5e6775333bbc/attributes'

Get application attributes response example

{
  "applicationattributes": [
    {
      "name": "sms_enabled",
      "value": "true"
    },
    {
      "name": "voice_enabled",
      "value": "true"
    }
  ]
}