Device Management APIs

You can use these APIs to manage your users' devices, such as retrieving all authenticating devices for a user as well as blocking and unblocking specific devices.

Get User Devices API

Gets a list of authenticated devices for the specified application and user.

HTTP Request

The API is invoked as a GET request to the following endpoint:

https://<host-name>/api/v1/mgmt/users/device-list

where <host-name> has the following value depending on the environment:

• Sandbox: admin.bindid-sandbox.io
• Production: admin.bindid.io
• Production EU: admin.eu.bindid.io

Request Header

Header Name	Value
Authorization	A valid bearer token (see Token API)

Request Parameters

Field	Description	Type
appId	Required. ID of the application for which you want to retrieve authenticating devices.	String
credentialsId	Required. API credentials ID used to create the access token that authorizes this request.	String
userId	Required. ID of the user whose devices you want to retrieve (the sub field returned in the claim of the ID token).	String

Request Example

GET /api/v1/mgmt/users/device-list?credentialsId=37b174b1.management_api_app.tid_a831ca3d.bindid.io&userId=4a42b9d6-6810-4caf-abc2-3a55fdeaa266&appId=acme_app

Authorization: Bearer q5fDE10-mlM4xEwl_UnhKjhvWOLHEbXqzJOYpGgxuB0

Response Headers

The response includes this HTTP header:

Header Name	Value
Content-Type	application/json

Response Body

The JSON object in the body has the following structure:

Field Name	Description	Type
data	JSON object containing authenticated devices, only returned when the value of status is success.	data
status	Indicates call success or failure.	String

data Object

Field Name	Description	Type
devices	Array containing authenticated device details.	Array of devices objects

devices Object

Field Name	Description	Type
blocked	Indicates whether the device is blocked (cannot be used for authentication).	Boolean
device_id	The device's ID.	String
device_model	The device model or the authenticated web browser version.	String
os_type	The device's OS.	String
os_version	The device's OS version.	String
first_seen_by_RP	The first time the device was used to authenticate the specified user for the specified application, in unix-epoch milliseconds.	Number
last_seen_by_RP	The last time the device was used to authenticate the specified user for the specified application, in unix-epoch milliseconds.	Number
registration_time_by_network	The first time the device used BindID to authenticate, which can be: LAST_24_HOURS, LAST_7_DAYS, LAST_28_DAYS, or OVER_28_DAYS.	String
last_seen_by_network	The last time the device used BindID to authenticate, which can be: LAST_24_HOURS, LAST_7_DAYS, LAST_28_DAYS, or OVER_28_DAYS.	String

Response Example

HTTP/2 200

Content-Type: application/json

{

"data": {

"devices": [

{

"device_id": "616310bf-a228-47dd-81e9-2a4709e576c3",

"os_type": "Mac OS",

"os_version": "10.15.7",

"device_model": "Chrome 96.0.4664.93",

"last_seen_by_network": "LAST_24_HOURS",

"registration_time_by_network": "LAST_7_DAYS",

"blocked": false,

"first_seen_by_RP": 1640331251285,

"last_seen_by_RP": 1642664161716

},

{

"device_id": "f1168610-01fa-4e82-b9c3-061a9562bcea",

"os_type": "Mac OS",

"os_version": "10.15.7",

"device_model": "Safari 15.0",

"last_seen_by_network": "LAST_24_HOURS",

"registration_time_by_network": "LAST_7_DAYS",

"blocked": true,

"first_seen_by_RP": 1641108964392,

"last_seen_by_RP": 1641134164941

}

]

},

"status": "success"

}

Failures

In addition to the common errors (see Introduction), the following error response code may be returned as part of a 4xx status response:

Status Code	Response Code	Description
400	app_not_found	The specified application cannot be found.
403	user_not_found	The specified user cannot be found.

Block User Device API

Blocks the specified device, which prevents the user from authenticating with that device.

HTTP Request

The API is invoked as a POST request to the following endpoint:

https://<host-name>/api/v1/mgmt/users/block-device

where <host-name> has the following value depending on the environment:

• Sandbox: admin.bindid-sandbox.io
• Production: admin.bindid.io
• Production EU: admin.eu.bindid.io

Request Header

Header Name	Value
Authorization	A valid bearer token (see Token API)
Content-Type	application/json

Request Body

A JSON object with these fields:

Field	Description	Type
deviceId	Required. The ID of the device you want to block.	String
credentialsId	Required. API credentials ID used to create the access token that authorizes this request.	String
userId	Required. The ID of the user whose device you want to block (the sub field returned in the claim of the ID token).	String

Request Example

POST /api/v1/mgmt/users/block-device

Authorization: Bearer k_lONS-upqKzUx_UWpmJBIiybpf2ZyEkmBTcUYkvSEI

Content-Type: application/json

{

"userId": "4a42b9d6-6810-4caf-abc2-3a55fdeaa266",

"credentialsId": "37b174b1.management_api_app.tid_a831ca3d.bindid.io",

"deviceId": "f1168610-01fa-4e82-b9c3-061a9562bcea"

}

Response Headers

The POST response includes this HTTP header:

Header Name	Value
Content-Type	application/json

Response Body

The JSON object in the body has the following structure:

Field Name	Description	Type
status	Indicates call success or failure.	String

Response Example

HTTP/2 200

Content-Type: application/json

{

"status": "success"

}

Failures

In addition to the common errors (see Introduction), the following error response codes may be returned as part of a 4xx status response:

Status Code	Response Code	Description
409	already_blocked	The specified device is already blocked.
403	user_not_found	The specified user cannot be found.

Block All User Devices API

Blocks all the specified user's devices, which prevents the user from authenticating with any of their devices.

HTTP Request

The API is invoked as a POST request to the following endpoint:

https://<host-name>/api/v1/mgmt/users/block-all-devices

where <host-name> has the following value depending on the environment:

• Sandbox: admin.bindid-sandbox.io
• Production: admin.bindid.io
• Production EU: admin.eu.bindid.io

Request Header

Header Name	Value
Authorization	A valid bearer token (see Token API)
Content-Type	application/json

Request Body

A JSON object with these fields:

Field	Description	Type
credentialsId	Required. API credentials ID used to create the access token that authorizes this request.	String
userId	Required. The ID of the user whose devices you want to block (the sub field returned in the claim of the ID token).	String

Request Example

POST /api/v1/mgmt/users/block-all-devices

Authorization: Bearer k_lONS-upqKzUx_UWpmJBIiybpf2ZyEkmBTcUYkvSEI

Content-Type: application/json

{

"userId": "4a42b9d6-6810-4caf-abc2-3a55fdeaa266",

"credentialsId": "37b174b1.management_api_app.tid_a831ca3d.bindid.io"

}

Response Headers

The POST response includes this HTTP header:

Header Name	Value
Content-Type	application/json

Response Body

The JSON object in the body has the following structure:

Field Name	Description	Type
status	Indicates call success or failure.	String

Response Example

HTTP/2 200

Content-Type: application/json

{

"status": "success"

}

Failures

In addition to the common errors (see Introduction), the following error response code may be returned as part of a 4xx status response:

Status Code	Response Code	Description
403	user_not_found	The specified user cannot be found.

Unblock User Device API

Unblocks the specified device, which allows the user to authenticate with that device.

HTTP Request

The API is invoked as a POST request to the following endpoint:

https://<host-name>/api/v1/mgmt/users/unblock-device

where <host-name> has the following value depending on the environment:

• Sandbox: admin.bindid-sandbox.io
• Production: admin.bindid.io
• Production EU: admin.eu.bindid.io

Request Header

Header Name	Value
Authorization	A valid bearer token (see Token API)
Content-Type	application/json

Request Body

A JSON object with these fields:

Field	Description	Type
deviceId	Required. The ID of the device you want to unblock.	String
credentialsId	Required. API credentials ID used to create the access token that authorizes this request.	String
userId	Required. The ID of the user whose device you want to unblock (the sub field returned in the claim of the ID token).	String

Request Example

POST /api/v1/mgmt/users/unblock-device

Authorization: Bearer k_lONS-upqKzUx_UWpmJBIiybpf2ZyEkmBTcUYkvSEI

Content-Type: application/json

{

"userId": "4a42b9d6-6810-4caf-abc2-3a55fdeaa266",

"credentialsId": "37b174b1.management_api_app.tid_a831ca3d.bindid.io",

"deviceId": "f1168610-01fa-4e82-b9c3-061a9562bcea"

}

Response Headers

The POST response includes this HTTP header:

Header Name	Value
Content-Type	application/json

Response Body

The JSON object in the body has the following structure:

Field Name	Description	Type
status	Indicates call success or failure.	String

Response Example

HTTP/2 200

Content-Type: application/json

{

"status": "success"

}

Failures

In addition to the common errors (see Introduction), the following error response codes may be returned as part of a 4xx status response:

Status Code	Response Code	Description
409	already_unblocked	The specified device is already unblocked.
403	user_not_found	The specified user cannot be found.

Unblock All User Devices API

Unblocks all the specified user's devices, which allows the user to authenticate with any of their registered devices.

HTTP Request

The API is invoked as a POST request to the following endpoint:

https://<host-name>/api/v1/mgmt/users/unblock-all-devices

where <host-name> has the following value depending on the environment:

• Sandbox: admin.bindid-sandbox.io
• Production: admin.bindid.io
• Production EU: admin.eu.bindid.io

Request Header

Header Name	Value
Authorization	A valid bearer token (see Token API)
Content-Type	application/json

Request Body

A JSON object with these fields:

Field	Description	Type
credentialsId	Required. API credentials ID used to create the access token that authorizes this request.	String
userId	Required. The ID of the user whose devices you want to unblock (the sub field returned in the claim of the ID token).	String

Request Example

POST /api/v1/mgmt/users/unblock-all-devices

Authorization: Bearer k_lONS-upqKzUx_UWpmJBIiybpf2ZyEkmBTcUYkvSEI

Content-Type: application/json

{

"userId": "4a42b9d6-6810-4caf-abc2-3a55fdeaa266",

"credentialsId": "37b174b1.management_api_app.tid_a831ca3d.bindid.io"

}

Response Headers

The POST response includes this HTTP header:

Header Name	Value
Content-Type	application/json

Response Body

The JSON object in the body has the following structure:

Field Name	Description	Type
status	Indicates call success or failure.	String

Response Example

HTTP/2 200

Content-Type: application/json

{

"status": "success"

}

Failures

In addition to the common errors (see Introduction), the following error response code may be returned as part of a 4xx status response:

Status Code	Response Code	Description
403	user_not_found	The specified user cannot be found.