Device API

The device API enables a web application to list devices that a user has (dynamically) registered, possibly on behalf of the user. This API can also be used to delete (deregister) a device entirely. For example, a user that loses a device may wish to revoke all permissions and access belonging to that device.

List devices

The list devices endpoint can be used to display information on each of the devices a user has registered.

Version 3

Endpoint: GET /oauth/api/v3/users/{userId}/devices

This endpoint requires basic authentication with valid API client credentials.

When no devices are found because the user does not exist or the user does not have any devices, a 404 Not Found is returned. When the user does have devices, an array with one or more devices is returned. Each device object has the following attributes.

Example result:

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

{
  "devices": [
    {
      "id": "fc4ef972-7167-4421-aa89-f109be79d7c2",
      "name": "Device X",
      "application": "application 1",
      "platform": "ANDROID",
      "created at": 1381322054000,
      "token_types": [
        "DEFAULT"
      ],
      "mobile_authentication_enabled": true,
      "push_authentication_enabled": true        
    },
    {
      "id": "451f5c34-3d03-4ce0-80bd-4676fc0eddf5",
      "name": "Device Y",
      "application": "application 2",
      "platform": "IOS",
      "created at": 1381322054000,
      "token_types": [
        "DEFAULT"
      ],
      "mobile_authentication_enabled": true,
      "push_authentication_enabled": false   
    }
  ]
}

Example error response:

{
  "error": "No devices found"
}

Versions 1 & 2

Endpoints:

• GET /oauth/api/v1/users/{userId}/devices
• GET /oauth/api/v2/users/{userId}/devices

This endpoint requires basic authentication with valid API client credentials.

When no devices are found because the user does not exist or the user does not have any devices, a 404 Not Found is returned. When the user does have devices, an array with one or more devices is returned. Each device object has the following attributes.

Note: In API version 2, new attributes were added (they are marked as v2 in the Version column).

Delete / revoke device

The delete device endpoint can be used to delete a device from the Token Server. This completely deregisters the user from the device: all access grants, access tokens, registered custom authentications, and mobile authentication enrollments are revoked on the Token Server. Note that this will remain on the device itself -- it simply will not be valid anymore server side.

Endpoint:

• DELETE /oauth/api/v1/users/{userId}/devices/{deviceId}
• DELETE /oauth/api/v2/users/{userId}/devices/{deviceId}
• DELETE /oauth/api/v3/users/{userId}/devices/{deviceId}

This endpoint requires basic authentication with valid API client credentials.

This endpoint always returns a 204 No Content response, independent of the execution result. In API versions 2 and higher, when there are multiple users (profiles) registered on a device, only data related to the provided userId will be deleted.

Example result:

HTTP/1.1 204 No Content
Cache-Control: no-store
Pragma: no-cache

Bulk delete / revoke device

The bulk delete device endpoint deletes all devices enrolled for a specific user. See Delete / revoke device for further details.

Endpoint:

• DELETE /oauth/api/v3/users/{userId}/devices

This endpoint requires basic authentication with valid API client credentials.

This endpoint returns a 204 No Content response.

Example result:

HTTP/1.1 204 No Content
Cache-Control: no-store
Pragma: no-cache

Disable fingerprint

The disable fingerprint endpoint can be used to revoke a fingerprint refresh token on a user's device. Note that this endpoint does not prevent a user from registering their fingerprint again.

Endpoints:

• POST /oauth/api/v2/users/{userId}/devices/{deviceId}/disableFingerprint
• POST /oauth/api/v3/users/{userId}/devices/{deviceId}/disableFingerprint

Both endpoints are functionally the same.

This endpoint requires basic authentication with valid API client credentials.

This endpoint always returns a 204 No Content response, independent of the execution result.

Disable mobile authentication

The disable mobile authentication can be used to disenroll a user's device for mobile authentication. When a the SDK enrolls a user for mobile authentication, the SDK and Token Server exchange public keys. The SDK must take an additional step to enroll for mobile authentication with push (and provide a push token).

When this endpoint is called for a user's device, the Token Server disenrolls the user's device for all types of mobile authentication (including push). The public keys are removed server side, and the push token (if it exists) is also dropped.

Note that this action does not prevent a user from enrolling the same device a second time for mobile authentication.

Endpoint:

• POST /oauth/api/v2/users/{userId}/devices/{deviceId}/disableMobileAuthentication
• POST /oauth/api/v3/users/{userId}/devices/{deviceId}/disableMobileAuthentication

Both endpoints are functionally the same.

This endpoint requires basic authentication with valid API client credentials.

This endpoint always returns a 204 No Content response, independent of the execution result.

Disable mobile authentication with push

The disable mobile authentication with push endpoint can be used to disenroll a user's device for push only. It removes the push token from the Token Server, but leaves the user's public key intact, allowing other forms of mobile authentication to remain working.

Note that this action does not prevent a user from re-enrolling for mobile authentication with push.

Endpoint:

• POST /oauth/api/v2/users/{userId}/devices/{deviceId}/disablePushAuthentication
• POST /oauth/api/v3/users/{userId}/devices/{deviceId}/disablePushAuthentication

Both endpoints are functionally the same.

This endpoint requires basic authentication with valid API client credentials.

This endpoint always returns a 204 No Content response, independent of the execution result.