Platform APIs
More PingIdentity APIs

Seen Devices API

Retrieve or update all the devices of a user, which are not the current primary and trusted devices.

Device representation

Parameter Name Type Description
applicationId* String The unique identifier of the PingID SDK customer mobile application.
deviceType* String Device platform.
Valid values:
  • Android
  • iPhone
deviceFingerprint* String Identifier of a device.
deviceName* String Model of the device, eg. iPhone 5S
firstSeenAt* Date The date and time of the first appearance of the device in PingID SDK.

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.
accessTime* Date Last date and time a user accessed a PingID SDK protected customer mobile 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.
ignored* boolean Indicates whether the device is in ignored mode.

When the user will try to authenticate from the device, PingID SDK immediately returns the authentication resource with status IGNORED.
ignoreStartTime Date

The date and time when the device ignored mode was enabled.

Optional.

The value may be returned from the call.

Rules:

  1. If ignoreStartTime is null and ignoreEndTime is set, the device will be ignored from now and until endTime.
  2. If ignoreStartTime is set and ignoreEndTime is null, the device will be ignored forever.
  3. If ignoreStartTime is set and ignoreEndTime is set, the device will be ignored in this time range.
  4. If both values are null, the device ignored mode is disabled.

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.
ignoreEndTime Date The date and time when the device ignored mode will expire.

Optional.

The value may be returned from the call.

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.
blocked boolean Indicates whether the device is blocked or should be updated to blocked.

Optional.

The value may be returned from the call.

If it is set to blocked, when the user will try to authenticate from the device PingID SDK immediately returns the Authentication resource with the status REJECTED.
blockStartTime* Date The date and time when the device became blocked.

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.
deniedTime* Date

The last date and time when the user was denied access from this device.

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.
*The value is returned from the call.

Available REST operations

HTTP Method Description
GET Retrieve all seen devices of a user
PUT Update a seen device of a user

Authorization

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

Retrieve all seen devices of the user: (GET)

Relative Path

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

Parameters

Parameter Name Type Description
accountId String The ID of the PingID SDK tenant.
applicationId String The unique identifier 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 seen devices of a user.

  • Retrieve all seen 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/seendevices'

  • Retrieve all seen 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/users/john.galt"
  },
  "account": {
    "href": "https://sdk.pingid.com/pingid/v1/accounts/e17f898d-3577-490d-baa7-64ceecf6b8a5"
  },
  "seendevices": [
    {
      "applicationId": "49b9ed37-31ce-488f-9c44-1fe1ed95f756",
      "deviceFingerprint": "H5SokIpRMUiS3ETOAsSI",
      "deviceType": "iPhone",
      "deviceName": "iPhone 5S",
      "firstSeenAt": 1490106748795,
      "accessTime": 1490173194952,
      "ignored": false,
      "blocked": false
    },
    {
      "applicationId": "49b9ed37-31ce-488f-9c44-1fe1ed95f756",
      "deviceFingerprint": "6frTx9ql3iqegs2TorqZ",
      "deviceType": "iPhone",
      "deviceName": "iPhone 5S",
      "firstSeenAt": 1490173208089,
      "accessTime": 1490173208089,
      "ignored": false,
      "blocked": true,
      "blockStartTime": 1490278220936
    },
    {
      "applicationId": "49b9ed37-31ce-488f-9c44-1fe1ed95f756",
      "deviceFingerprint": "TNNt18WSCDWPh4VLy3AS",
      "deviceType": "iPhone",
      "deviceName": "iPhone 5S",
      "firstSeenAt": 1490103373062,
      "accessTime": 1490103562326,
      "ignored": false,
      "blocked": false
    },
    {
      "applicationId": "49b9ed37-31ce-488f-9c44-1fe1ed95f756",
      "deviceFingerprint": "9Pzk1Y0YQBj5XwKcSBWm",
      "deviceType": "iPhone",
      "deviceName": "iPhone 5S",
      "firstSeenAt": 1489504186815,
      "accessTime": 1489504186815,
      "ignored": false,
      "blocked": false
    },
    {
      "applicationId": "49b9ed37-31ce-488f-9c44-1fe1ed95f756",
      "deviceFingerprint": "Y2NzeXMzNEtKSG1XQWhoZUFzRmE=",
      "deviceType": "Android",
      "deviceName": "samsung SM-G920F",
      "firstSeenAt": 1489504726009,
      "accessTime": 1489504726009,
      "ignored": false,
      "blocked": false
    },
    {
      "applicationId": "49b9ed37-31ce-488f-9c44-1fe1ed95f756",
      "deviceFingerprint": "V0U5Z25tME4zRUw0UlFMV3gwR0k=",
      "deviceType": "Android",
      "deviceName": "samsung SM-G920F",
      "firstSeenAt": 1490102441380,
      "accessTime": 1490173187908,
      "ignored": false,
      "blocked": false
    }
  ]
}

Update a seen device of a user: (PUT)

Relative Path

/accounts/{accountId}/applications/{applicationId}/users/{username}/seendevices/{seenDeviceFp}

Parameters

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

  • Update a seen 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 '{ \ 
   "applicationId": "49b9ed37-31ce-488f-9c44-1fe1ed95f756", \ 
   "deviceType": "iPhone", \ 
   "deviceFingerprint": "6frTx9ql3iqegs2TorqZ", \ 
   "deviceName": "iPhone 5S", \ 
   "firstSeenAt": 1490173208089, \ 
   "accessTime": 1490173208089, \ 
   "ignored": false, \ 
   "blocked": true \ 
 }' 'https://sdk.pingid.com/pingid/v1/accounts/e17f898d-3577-490d-baa7-64ceecf6b8a5/applications/49b9ed37-31ce-488f-9c44-1fe1ed95f756/users/john.galt/seendevices/6frTx9ql3iqegs2TorqZ'

  • Update a seen device of a user: (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/seendevices/{deviceFingerprint}"
  },
  "account": {
    "href": "https://sdk.pingid.com/pingid/v1/accounts/e17f898d-3577-490d-baa7-64ceecf6b8a5"
  },
  "applicationId": "49b9ed37-31ce-488f-9c44-1fe1ed95f756",
  "deviceFingerprint": "6frTx9ql3iqegs2TorqZ",
  "deviceType": "iPhone",
  "deviceName": "iPhone 5S",
  "firstSeenAt": 1490173208089,
  "accessTime": 1490173208089,
  "ignored": false,
  "blocked": true,
  "blockStartTime": 1490278220936
}