API Guide - TrustScore

  • Updated on Apr 27, 2022

Set Max Trust Level

Banyan’s algorithms calculate a TrustScore (0 to 100) and convert it to a human-readable TrustLevel (AlwaysDeny, Low, Medium, High, AlwaysAllow) for every access based on User, Device and Application context. This API enables Admins to apply a negative override to Banyan’s scoring algorithm, by setting a maximum possible TrustLevel for any given User or Device.

HTTP Request

POST /v1/set_max_trust_level

URL Parameters

N/A

Query Parameters

Parameter Format Description
Email String Specify the user to set the max TrustLevel for
SerialNumber String Specify the device to set the max TrustLevel for

Note: You need to provide only one of the Query Parameters, else you will get a BadRequest error.

Example requests:

POST /v1/set_max_trust_level?Email=user@example.com
POST /v1/set_max_trust_level?SerialNumber=C1234X9876

Request Headers

Authorization: Bearer $AUTHTOKEN

ContentType: application/json

Request Body

The request must be JSON that contains “Level”, “ExtSource” and “Reason”. If any one is empty, the API will return an error.

Key Format Description
Level String can be one of (AlwaysDeny, Low, Medium, High, AlwaysAllow)
Reason String explanation to be displayed in console and to the user
ExtSource String name of the external source. Eg. CarbonBlack, CrowdStrike etc.

Example JSON body:

{
    "Level": "AlwaysDeny",
    "Reason": "Known malware MWS-2019-9842 detected on device - quarantine action taken.",
    "ExtSource": "CarbonBlack"
}

Status Codes and Errors

Value Description
200 OK
500 Internal Server Error
400 Bad Request

Response Headers

N/A

Response Body

{
    "TrustType": "External",
    "TrustID": "1234-5678",
    "Score": 0,
    "Level": "AlwaysDeny",
    "Reason": "Known malware MWS-2019-9842 detected on device - quarantine action taken.",
    "ExtSource": "CarbonBlack",
    "FactorsJSON": "",
    "CreatedAt": 1556712776991998000,
    "DeletedAt": 0,
    "LastUpdatedAt": 1556712809873130000
}

Error response body

Returns error when the authentication token provided is invalid.

{
  "error": {
    "code": "TOKEN_INVALID",
    "message": "Authentication token is invalid"
  },
  "request_id": "beda45a6-59e6-4dcf-9eb9-8218afb5a596",
  "Message": "Authentication token is invalid"
}

Returns error when the authentication token provided has expired.

{
  "error": {
    "code": "TOKEN_EXPIRED",
    "message": "Authentication token has expired"
  },
  "request_id": "beda45a6-59e6-4dcf-9eb9-8218afb5a596",
  "Message": "Authentication token has expired"
}

Returns error when the internal server error

{
  "error": {
    "code": "INTERNAL_SERVER_ERROR",
    "message": "Internal server error has occurred while processing the request"
  },
  "request_id": "beda45a6-59e6-4dcf-9eb9-8218afb5a596",
  "Message": "Internal server error has occurred while processing the request"
}

Returns error when unauthorized access with non-testdrive org

{
  "error": {
    "code": "UNAUTHORIZED_ACCESS",
    "message": "Unauthorized access"
  },
  "request_id": "beda45a6-59e6-4dcf-9eb9-8218afb5a596",
  "Message": "Unauthorized access"
}