API Guide - UsersDevices
- Updated on Apr 27, 2022
- Get the End Users in an Organization
- Get the Devices in an Organization
- Delete Enduser Device
- Ban & Unban Devices
- DELETE enduser
Get the End Users in an Organization
Fetches user information (such as user attributes and TrustScoring details) about all the users in your organization.
NOTE: To maintain backwards compatibility, this API response changes when you add the pagination query parameters: skip
and limit
.
HTTP Request
GET /v1/endusers
URL Parameters
N/A
Query Parameters
Parameter | Format | Description |
---|---|---|
Serialnumber | String | Filter by serial number of device |
String | Filter by email address of user | |
Skip | Int | Specify the number of records to skip |
Limit | Int | Specify the number of records you want returned |
Name | String | Filter by enduser’s name |
Order | String | Sorts end users list by ascending (asc ) or descending (desc ) order, depending on orderby |
OrderBy | String | Sorts end users list by given value (such as name , email ) |
Request Headers
Authorization: Bearer $AUTHTOKEN
Request Body
N/A
Status Codes and Errors
Value | Description |
---|---|
200 | OK |
500 | Internal Server Error |
400 | Bad Request |
Response Headers
N/A
HTTP Response Body - Non-Paginated
Example for the Non-Paginated API:
GET /v1/endusers?email=foo+carly@banyanops.com
[
{
"Name": "Carly Contractor",
"Email": "foo+carly@banyanops.com",
"Groups": "contractors",
"LastLogin": 1595623756579573745,
"LoginCount": 12884901929,
"SerialNumbers": [
"PF1H8FJD123",
],
"TrustData": {
"EntityTrustscore": 100,
"OverrideTrustscore": 100,
"AccessTrustscore": 100,
"OverrideActive": "FALSE",
"Level": "AlwaysAllow",
"UpdatedAt": 1560321695332747860,
"Factors": []
},
"Roles": [
"all-contractors",
"exempted-users"
]
}
]
HTTP Response Body - Paginated
Example for the Paginated API:
GET /v1/endusers?skip=0&limit=10
{
"endusers": [
{
"Name": "Pradip Shrama",
"Email": "pradip.example@joshsoftware.com",
"Groups": "Type10Employee,Engineering,Everyone,Type6Employee,Type7Employee,Type1Employee,Type4Employee,Type9Employee,Type3Employee,Type5Employee,Type2Employee,Type8Employee",
"TrustData": {
"EntityTrustscore": 100,
"OverrideTrustscore": 100,
"AccessTrustscore": 100,
"OverrideActive": "FALSE",
"Level": "AlwaysAllow",
"UpdatedAt": 1575033790699519866,
"Factors": []
},
"Roles": ["Engineering-users"]
},
{
"Name": "Omkar Patil",
"Email": "omkar.example@joshsoftware.com",
"Groups": "Engineering,Everyone",
"TrustData": {
"EntityTrustscore": 100,
"OverrideTrustscore": 100,
"AccessTrustscore": 100,
"OverrideActive": "FALSE",
"Level": "AlwaysAllow",
"UpdatedAt": 1581405438206764451,
"Factors": []
},
"Roles": ["Engineering-users"]
},
{
"Name": "Akshay khatu",
"Email": "example@joshsoftware.com",
"Groups": "Engineering,Everyone",
"TrustData": {
"EntityTrustscore": 100,
"OverrideTrustscore": 100,
"AccessTrustscore": 100,
"OverrideActive": "FALSE",
"Level": "AlwaysAllow",
"UpdatedAt": 1586334782380580944,
"Factors": []
},
"Roles": ["Engineering-users"]
}
],
"count": 54
}
Get the Devices in an Organization
Fetches device information (such as device attributes, device manager data and TrustScoring details) about all the devices in your organization.
NOTE: To maintain backwards compatibility, this API response changes when you add the pagination query parameters: skip
and limit
.
HTTP Request
GET /v1/devices
URL Parameters
N/A
Query Parameters
Parameter | Format | Description |
---|---|---|
Serialnumber | String | Filter by serial number of device |
String | Filter by email address of user | |
Skip | Int | Specify the number of records to skip |
Limit | Int | Specify the number of records you want returned |
Model | String | Filter by model of device (such as MacBook , iPhone , 20QVS0FP00 (Lenovo ThinkPad)) |
DeviceFriendlyName | String | Filter by friendly name of device |
Order | String | Sorts devices list by ascending (asc ) or descending (desc ) order, depending on orderby |
OrderBy | String | Sorts devices list by given value (such as serialnumber , devicefriendlyname , or model ) |
Request Headers
Authorization: Bearer $AUTHTOKEN
Request Body
N/A
Status Codes and Errors
Value | Description |
---|---|
200 | OK |
500 | Internal Server Error |
400 | Bad Request |
Response Headers
N/A
HTTP Response Body - Non-Paginated
Example for the Non-Paginated API:
/devices?serialnumber=27812a90a19df067
[
{
"DeviceID": "1864047b-ed59-48ed-b448-492d3b0feb98",
"SerialNumber": "27812a90a19df067",
"DeviceFriendlyName": "",
"Emails": [
"jack@example.com"
],
"LastLogin": 1587370622671500176,
"LoginCount": 2147483647,
"Ownership": "Employee Owned",
"Platform": "Android",
"Model": "AOSP on IA Emulator",
"Architecture": "i686",
"RegisteredStatus": "TRUE",
"MdmData": {
"Timestamp": 1587453424955162624,
"Source": "BNN",
"CompromisedStatus": "FALSE",
"CompliantStatus": ""
},
"trust": {
"value": 100,
"level": "High",
"status": "Reporting",
"last_evaluated":{
"last_evaluated_at": 1603985589951,
"last_evaluated_value": 80,
"last_evaluated_level": "High",
"last_evaluated_factors": [{
"name": "AutoUpdateEnabled",
"value": "true",
"type": "internal",
"source": "banyan",
"description": "",
"remediation": {
"description": "",
"url": ""
}
}]
},
"expired_at": 1603985580051,
"factors": [{
"name": "AutoUpdateEnabled",
"value": "true",
"type": "internal",
"source": "banyan",
"description": "",
"remediation": {
"description": "",
"url": ""
}
}]
},
"TrustData": {
"EntityTrustscore": 99,
"OverrideTrustscore": 100,
"AccessTrustscore": 99,
"OverrideActive": "FALSE",
"Level": "High",
"UpdatedAt": 1587453425159874138,
"Factors": [
{
"Name": "DiskEncryptionEnabled",
"Value": "true",
"Type": "internal",
"Source": "banyan",
"Description": "",
"RemediationDescription":"",
"RemediationURL":""
},
{
"Name": "NotJailbroken",
"Value": "true",
"Type": "internal",
"Source": "banyan",
"Description": "",
"RemediationDescription":"",
"RemediationURL":""
},
{
"Name": "ScreenLockEnabled",
"Value": "true",
"Type": "internal",
"Source": "banyan",
"Description": "",
"RemediationDescription":"",
"RemediationURL":""
},
{
"Name": "UpToDateOS",
"Value": "true",
"Type": "internal",
"Source": "banyan",
"Description": "",
"RemediationDescription":"",
"RemediationURL":""
}
]
},
"Roles": [
"all-qa-users",
"all-engineering-users"
],
"Banned": "FALSE",
"OS": "",
"AppVersion": ""
}
]
HTTP Response Body - Paginated
Example for the Paginated API:
GET /v1/devices?skip=0&limit=2
{
"devices": [
{
"DeviceID": "94be2e72-4ce5-41c0-a76d-b0bbd865a1fb",
"SerialNumber": "6457fa4aa96e29c7",
"DeviceFriendlyName": "",
"Ownership": "Employee Owned",
"Platform": "Android",
"Model": "AOSP on IA Emulator",
"Architecture": "i686",
"RegisteredStatus": "TRUE",
"MdmData": {
"Timestamp": 0,
"Source": "BNN",
"CompromisedStatus": "FALSE",
"CompliantStatus": ""
},
"trust": {
"value": 100,
"level": "High",
"status": "Reporting",
"last_evaluated":{
"last_evaluated_at": 1603985589951,
"last_evaluated_value": 80,
"last_evaluated_level": "High",
"last_evaluated_factors": [{
"name": "AutoUpdateEnabled",
"value": "true",
"type": "internal",
"source": "banyan",
"description": "",
"remediation": {
"description": "",
"url": ""
}
}]
},
"expired_at": 1603985580051,
"factors": [{
"name": "AutoUpdateEnabled",
"value": "true",
"type": "internal",
"source": "banyan",
"description": "",
"remediation": {
"description": "",
"url": ""
}
}]
},
"TrustData": {
"EntityTrustscore": 100,
"OverrideTrustscore": 100,
"AccessTrustscore": 100,
"OverrideActive": "FALSE",
"Level": "AlwaysAllow",
"UpdatedAt": 1594999256162778464,
"Factors": [
{
"Name": "Bnn",
"Value": "true",
"Type": "internal",
"Source": "banyan",
"Description": "",
"RemediationDescription":"",
"RemediationURL":""
}
]
},
"Roles": [
"Developer"
],
"Banned": "FALSE",
"OS": "",
"AppVersion": ""
},
{
"DeviceID": "5b8d81a5-4bbe-41f1-a9c3-5cf19efb5543",
"SerialNumber": "CEA60A5857D74186BEAD6F1027BFA033",
"DeviceFriendlyName": "Jack’s iPhone",
"Ownership": "Employee Owned",
"Platform": "iOS",
"Model": "iPhone Xr",
"Architecture": "amd64",
"RegisteredStatus": "TRUE",
"MdmData": {
"Timestamp": 0,
"Source": "BNN",
"CompromisedStatus": "FALSE",
"CompliantStatus": ""
},
"trust": {
"value": 100,
"level": "High",
"status": "Reporting",
"last_evaluated":{
"last_evaluated_at": 1603985589951,
"last_evaluated_value": 80,
"last_evaluated_level": "High",
"last_evaluated_factors": [{
"name": "AutoUpdateEnabled",
"value": "true",
"type": "internal",
"source": "banyan",
"description": "",
"remediation": {
"description": "",
"url": ""
}
}]
},
"expired_at": 1603985580051,
"factors": [{
"name": "AutoUpdateEnabled",
"value": "true",
"type": "internal",
"source": "banyan",
"description": "",
"remediation": {
"description": "",
"url": ""
}
}]
},
"TrustData": {
"EntityTrustscore": 100,
"OverrideTrustscore": 100,
"AccessTrustscore": 100,
"OverrideActive": "FALSE",
"Level": "AlwaysAllow",
"UpdatedAt": 1594998334145175888,
"Factors": [
{
"Name": "Bnn",
"Value": "true",
"Type": "internal",
"Source": "banyan",
"Description": "",
"RemediationDescription":"",
"RemediationURL":""
}
]
},
"Roles": [
"Developer"
],
"Banned": "FALSE",
"OS": "",
"AppVersion": ""
}
],
"count": 27
}
Delete Enduser Device
Deletes an enduser device and revokes associated client certificate(s).
HTTP Request
DELETE /v1/v1/delete_device?SerialNumber=<SerialNumber>&Email=<Email>
URL Parameters
N/A
CURL request
curl -X DELETE “api_endpoint/v1/v1/delete_device?SerialNumber=TBH121231&Email=trell@mail.com” -H ‘authorization: Bearer tokenxxx’
Query Parameters
Parameter | Format | Description |
---|---|---|
SerialNumber | String | serial number of device (compulsary parameter) |
String | email associated with device |
Request Headers
Authorization: Bearer $AUTHTOKEN
Request Body
N/A
Behavior when the email query parameter is included
Enduser-Device mapping(s) will be deleted from the database for the mentioned SerialNumber and email. Associated certificate(s) will also get revoked. #{:.subhead} i. If the mentioned user(user with stated email) is registered on only the mentioned device(device with stated serial number) then that user will also get deleted, else the user will remain intact. #{:.subhead} ii. If the mentioned device has only the mentioned user registered then the device will also get deleted, else the device will remain intact.
Behavior when the email query parameter is not included
Enduser-Device mapping(s) will be deleted from the database for the mentioned SerialNumber. Device with the mentioned SerialNumber will also get deleted. All certificates associated with the device will also get revoked. #{:.subhead} i. If any user(s) is/are associated with only the mentioned device then that/those user(s) will also get deleted else that/those user(s) will remain intact .
Status Codes and Errors
Value | Description |
---|---|
200 | OK |
400 | Bad Request |
500 | Internal Server Error |
Response Headers
N/A
HTTP Response Body
"Successfully deleted end user device"
Ban & Unban Devices
Updates all end user devices for given serial number. This endpoint can be used to ban/unban a device if the device object contains banned="TRUE"/"FALSE"
field.
HTTP Request
POST /v1/mdm/update_device?SerialNumber=<SerialNumber>
URL Parameters
N/A
Query Parameters
Parameter | Format | Description |
---|---|---|
SerialNumber | String | Serial number of device(s) to be updated |
Request Headers
Authorization: Bearer $AUTHTOKEN
ContentType: application/json
Request Body
[
{
"Model": "lenovo thinkpad",
"Ownership": "CorporateDedicated",
"Platform": "darwin",
"Architecture": "hello123123",
"Banned" : "FALSE",
}
]
Status Codes and Errors
Value | Description |
---|---|
200 | OK |
500 | Internal Server Error |
400 | Bad Request |
Response Headers
N/A
Response Body
[
{
"Message": "Success"
}
]
DELETE enduser
This api marks endusers as inactive, checks the devices associated with the user, if the device has no more active users then such devices are marked as inactive too.
Authorization needed: Admin
HTTP Request
DELETE /v2/endusers
URL Parameters
N/A
Request Headers
Authorization: Bearer $AUTHTOKEN
Request Body
{
"enduser_ids" : [
"725dc2fb-b162-45bd-8d91-9902c31afdf4",
"725dc2fb-b162-45bd-8d91-9902c31afdg7",
"725dc2fb-b162-45bd-8d91-9902c31affr5"
]
}
Status Codes and Errors
Value | Description |
---|---|
200 | OK |
401 | Unauthorized |
400 | Bad Request |
500 | Internal Server Error |
Response Headers
N/A
HTTP Response Body
200 Ok
{
"request_id": "",
"error_code": 0,
"error_description": "",
"data": "successfully marked the endusers as inactive"
}
400 Bad Request
{
"request_id": "",
"error_code": 400,
"error_description": "record not found",
"data": null
}
500 Ok
{
"request_id": "",
"error_code": 500,
"error_description": "error occoured while marking the endusers as inactive",
"data":null
}