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
Parameter | Description |
---|---|
userId |
Identifier of the user |
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.
Attribute | Description |
---|---|
id |
UUID identifying the device |
name |
The device name |
application |
A web client / group of dynamic clients that use the same configuration |
platform |
Platform / os of the device |
created_at |
Timestamp when device was connected; if no device is connected, this parameter stays empty |
token_types |
List of access token types issued for a device (possible values DEFAULT and FINGER_PRINT ) |
last_login |
Date of the last login using a device |
mobile_authentication_enabled |
true if a device is enrolled for mobile authentication |
push_authentication_enabled |
true if a device is enrolled for mobile authentication with push |
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
Parameter | Description |
---|---|
userId |
Identifier of the user |
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).
Attribute | Description | Version |
---|---|---|
id |
UUID identifying the device | v1 |
name |
The device name | v1 |
application |
A web client / group of dynamic clients that use the same configuration | v1 |
platform |
Platform / os of the device | v1 |
created_at |
Timestamp when device was connected; if no device is connected, this parameter stays empty | v1 |
token_types |
List of access token types issued for a device (possible values DEFAULT and FINGER_PRINT ) |
v2 |
last_login |
Date of the last login using a device | v2 |
mobile_authentication_enabled |
true if a device is enrolled for mobile authentication, and mobile authentication with push |
v2 |
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}
Parameter | Description |
---|---|
userId |
Identifier of the user |
deviceId |
Identifier of the device |
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
Parameter | Description |
---|---|
userId |
Identifier of the user |
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.
Parameter | Description |
---|---|
userId |
Identifier of the user |
deviceId |
Identifier of the device |
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.
Parameter | Description |
---|---|
userId |
Identifier of the user |
deviceId |
Identifier of the device |
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.
Parameter | Description |
---|---|
userId |
Identifier of the user |
deviceId |
Identifier of the device |
This endpoint requires basic authentication with valid API client credentials.
This endpoint always returns a 204 No Content
response, independent of the execution result.