Platform APIs
More PingIdentity APIs

User Devices API

Use this API to manage trusted devices. A user may have multiple trusted devices per application, as configured by the administrator, but only one primary device.

Device representation

Parameter Name Type Description
id String Unique identifier of a trusted device in PingID SDK server.
deviceType String Device platform.

Valid values:

  • Android
  • iPhone
  • SMS
  • Voice
  • Email
deviceFingerprint String Identifier of a device.
deviceName String Model of the device, for example, iPhone 5S.
This parameter is empty for OTP devices (SMS, voice, email).
deviceNickname String The device nickname, up to a maximum of 100 characters. All language character sets are permitted. If not specified, the default is the value of deviceName.
deviceRole String Role of the device in the user's network:
Valid values:
  • Primary
  • Trusted
enrollmentTime Date

The date and time of the first registration of the device, in the context of the application.

Format:

The ISO 8601 representation of a date (also as defined in RFC 3339) and SHOULD be presented in the UTC time zone.

Dates presented in a different time zone should be converted to UTC or stored with a time zone identifier so that date and time calculations can be applied.
applicationId String The ID of the PingID SDK customer mobile application.
bypassExpiration Date The date and time when the user's device enabled bypass mode will expire.

Format:

The ISO 8601 representation of a date (also as defined in RFC 3339) and SHOULD be presented in the UTC time zone.

Dates presented in a different time zone should be converted to UTC or stored with a time zone identifier so that date and time calculations can be applied.
bypassed boolean

The value returns from the call.

Indicates whether the user’s device is in bypass mode.

If the user’s device is in bypass mode, PingID SDK doesn’t validate the device.

When the user will try to authenticate from the device, PingID SDK immediately returns the Authentication resource with the status BYPASS.
phoneNumber String The device phone number, if the device is an SMS device. If the device is not an SMS device, this parameter is empty.
countryCode String The country code for the device phone number, if the device is an SMS device. If the device is not an SMS device, this parameter is empty.
pushEnabled String Whether the device can receive a push notification, if it is a mobile application. For SMS this parameter is always false.
osVersion String The device's operating system and version, if the device is a mobile application. For SMS this parameter is empty.
applicationVersion String The device's application version, if the device is a mobile application. For SMS this parameter is empty.
emailAddress String The device email address, if the device is an email device. If the device is not an email device, this parameter is empty.

The following parameters are empty for email devices:

  • pushEnabled
  • osVersion
  • applicationVersion
  • deviceName
rooted boolean Indicates whether the user's device is rooted.

Available REST operations:

HTTP Method Description
GET Retrieve all trusted devices of the user
POST Retrieve all trusted devices of the user
PATCH Patch the trusted device of the user
PUT Rename a trusted device of the user
DELETE Unpair the trusted device of the user

Authorization

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

Retrieve all trusted devices of the user: (GET)

Relative Path

Application specific user devices:

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

User devices irrespective of applications:

/accounts/{accountId}/users/{username}/devices

Parameters

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

This example shows how to retrieve all trusted devices of a user.

  • Retrieve all trusted devices of a user: (GET) request 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/devices'

  • Retrieve all seen trusted devices of a user: (GET) response example:

    {
  "application": {
    "href": "https://sdk.pingid.com/pingid/v1/accounts/e17f898d-3577-490d-baa7-64ceecf6b8a5/applications/49b9ed37-31ce-488f-9c44-1fe1ed95f756"
  },
  "user": {
    "href": "https://sdk.pingid.com/pingid/v1/accounts/e17f898d-3577-490d-baa7-64ceecf6b8a5/applications/49b9ed37-31ce-488f-9c44-1fe1ed95f756/users/john.galt"
  },
  "account": {
    "href": "https://sdk.pingid.com/pingid/v1/accounts/e17f898d-3577-490d-baa7-64ceecf6b8a5"
  },
  "devices": [
    {
      "deviceType": "iPhone",
      "id": "04e2eed4-c05d-b22d-04e2-eed4c05db22d",
      "deviceFingerprint": "6frTx9ql3iqegs2TorqZ",
      "deviceName": "iPhone 5S",
      "deviceRole": "primary",
      "enrollmentTime": 1490173219016,
      "applicationId": "49b9ed37-31ce-488f-9c44-1fe1ed95f756",
      "bypassed": false
    },
    {
      "deviceType": "Android",
      "id": "5827501b-01e7-ba44-5827-501b01e7ba44",
      "deviceFingerprint": "V0U5Z25tME4zRUw0UlFMV3gwR0k=",
      "deviceName": "samsung SM-G920F",
      "deviceRole": "trusted",
      "enrollmentTime": 1490173144345,
      "applicationId": "49b9ed37-31ce-488f-9c44-1fe1ed95f756",
      "bypassed": false
    }
  ]
}

Retrieve all trusted devices of the user: (POST)

Relative Path

Application specific user devices:

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

/accounts/{accountId}/applications/{applicationId}/users/{username}/devices/filter”

Parameters

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

Request Body

Parameter Name Type Description
filter String Filter object to filter user devices by mobile payload received from application.

This example shows how to retrieve all trusted devices of a user.

  • Retrieve all trusted devices of a user: (POST) request example:

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

  • Retrieve all seen trusted devices of a user: (POST) response example:

    {
  "application": {
    "href": "https://sdk.pingid.com/pingid/v1/accounts/e17f898d-3577-490d-baa7-64ceecf6b8a5/applications/49b9ed37-31ce-488f-9c44-1fe1ed95f756"
  },
  "user": {
    "href": "https://sdk.pingid.com/pingid/v1/accounts/e17f898d-3577-490d-baa7-64ceecf6b8a5/applications/49b9ed37-31ce-488f-9c44-1fe1ed95f756/users/john.galt"
  },
  "account": {
    "href": "https://sdk.pingid.com/pingid/v1/accounts/e17f898d-3577-490d-baa7-64ceecf6b8a5"
  },
  "devices": [
    {
      "deviceType": "iPhone",
      "id": "04e2eed4-c05d-b22d-04e2-eed4c05db22d",
      "deviceFingerprint": "6frTx9ql3iqegs2TorqZ",
      "deviceName": "iPhone 5S",
      "deviceRole": "primary",
      "enrollmentTime": 1490173219016,
      "applicationId": "49b9ed37-31ce-488f-9c44-1fe1ed95f756",
      "bypassed": false
    },
    {
      "deviceType": "Android",
      "id": "5827501b-01e7-ba44-5827-501b01e7ba44",
      "deviceFingerprint": "V0U5Z25tME4zRUw0UlFMV3gwR0k=",
      "deviceName": "samsung SM-G920F",
      "deviceRole": "trusted",
      "enrollmentTime": 1490173144345,
      "applicationId": "49b9ed37-31ce-488f-9c44-1fe1ed95f756",
      "bypassed": false
    }
  ]
}

Update a trusted device of a user: (PATCH)

Relative Path

/accounts/{accountId}/users/{username}/devices/{deviceId}

Parameters

Parameter Name Type Description
accountId String The ID of the PingID SDK tenant.
username String The user's unique name in PingID SDK, per tenant.
deviceId String The unique identifier of a trusted device.

Request body

Parameter Name Type Description
deviceRole String Role of the device in the users network.
Valid values:
  • Primary
  • Trusted
bypassExpiration Date The date and time when the user's device enabled bypass mode will expire (in UNIX epoch format)

  • Update a trusted device of a user: (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": "/deviceRole",  \ 
              "value": "primary"  \ 
       } \ 
   ]  \ 
 }' 'https://sdk.pingid.com/pingid/v1/accounts/e17f898d-3577-490d-baa7-64ceecf6b8a5/users/john.galt/devices/5827501b-01e7-ba44-5827-501b01e7ba44'

  • Update a trusted device of a user: (PATCH) respone example:

    {
  "self": {
    "href": "https://sdk.pingid.com/pingid/v1/accounts/e17f898d-3577-490d-baa7-64ceecf6b8a5/users/john.galt/devices/5827501b-01e7-ba44-5827-501b01e7ba44"
  },
  "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"
  },
  "deviceType": "Android",
  "id": "5827501b-01e7-ba44-5827-501b01e7ba44",
  "deviceFingerprint": "V0U5Z25tME4zRUw0UlFMV3gwR0k=",
  "deviceName": "samsung SM-G920F",
  "deviceRole": "primary",
  "enrollmentTime": 1490173144345,
  "bypassed": false

    }

Rename the trusted device of the user (PUT)

Relative Path

/accounts/{accountId}/users/{username}/devices/{deviceId}/deviceNickname

Parameters

Parameter Name Type Description
accountId String The ID of the PingID SDK tenant.
username String The user's unique name in PingID SDK, per tenant.
deviceId String The unique identifier of a trusted device.

Request body

Parameter Name Type Description
deviceNickname String The device nickname. This parameter may not be empty, and may be up to a maximum of 100 characters. All language character sets are permitted.

  • Rename a trusted device of a user: (PUT) request example:

    curl -X PUT \
 --header 'Content-Type: application/json' \
 --header 'Accept: application/json' \
 --header 'Authorization: PINGID-HMAC=<JWT>' -d '{ \
 "deviceNickname": "New nickname" \
 }' 'https://sdk.pingid.com/pingid/v1/accounts/e17f898d-3577-490d-baa7-64ceecf6b8a5/users/john.galt/devices/5827501b-01e7-ba44-5827-501b01e7ba44/deviceNickname'
    `

  • Rename a trusted device of a user: (PUT) response example:

    no content

Unpair the trusted device of the user (DELETE)

When a device is unpaired on the server, it is automatically unpaired on the mobile SDK.

Relative Path

/accounts/{accountId}/users/{username}/devices/{deviceId}

Parameters

Parameter Name Type Description
accountId String The ID of the PingID SDK tenant.
username String The user's unique name in PingID SDK, per tenant.
deviceId String The unique identifier of a trusted device.

  • Unpair a trusted device of a user: (DELETE) request example:

    curl -X DELETE \
 --header 'Accept: application/json' \
 --header 'Authorization: PINGID-HMAC=<JWT>' \
'https://sdk.pingid.com/pingid/v1/accounts/e17f898d-3577-490d-baa7-64ceecf6b8a5/users/john.galt/devices/5827501b-01e7-ba44-5827-501b01e7ba44'

  • Unpair a trusted device of a user: (DELETE) response example:

    no content