BlackBerry CylancePROTECT, CylanceOPTICS User Manual

Cylance®API

User API v2.0 Guide

Product: CylancePROTECT® and CylanceOPTICS

Document: Cylance API Guide. This guide is a succinct resource for analysts, administrators, and customers who are reviewing or evaluating the product.

Document Release Date: v2.0 rev34, December 2020

About BlackBerry Cylance®: BlackBerry Cylance develops artificial intelligence to deliver prevention-first, predictive security products and smart, simple, secure solutions that change how organizations approach endpoint security. BlackBerry Cylance provides fullspectrum predictive threat prevention and visibility across the enterprise to combat the most notorious and advanced cybersecurity attacks, fortifying endpoints to promote security hygiene in the security operations center, throughout global networks, and even on employees’ home networks. With AI-based malware prevention, threat hunting, automated detection and response, and expert security services, BlackBerry Cylance protects the endpoint without increasing staff workload or costs.

Copyright: © 2020 BlackBerry Cylance Inc. All Rights

Reserved.

.

Tableof Contents

- 3 -

Contents

Table of Contents	3
Application Management	9
Application Management	10
To Add an Application	10
To Edit an Application	13
To Delete an Application	14
To Regenerate an Application Control	15
Copy Tenant ID	16
API in Audit Logs	16
RESTful API	18
Authentication and Authorization	19
Application	19
Service Endpoint	19
Authentication	20
Authentication Token	20
Generating the Authentication and Access Tokens	21
Token Lifecycle	23
Request / Response Model	23
Authorization	24
Access Token	24
Response Status Codes	24
API Rate Limit	25
About Device ID	25
About Zone ID	26
User API	27
Create User	28
Get Users	31
Get User	34
Update User	36
Delete User	38
Send Invite Email	39
Send Request Password Email	41
Device API	42

Cylance User API Guide, v2.0 rev34, December 2020 | 4

Get Devices	43
Get Devices Extended	46
Get Device Count	49
Get Device	51
Get Device by MAC Address	53
Get Device by Hostname	56
Update Device	59
Get Device Threat	60
Update Device Threat	62
Get Zone Devices	64
Get Agent Installer Link	65
Delete Devices	68
Global List API	71
Get Global List	72
Add to Global List	74
Delete From Global List	76
Policy API	78
Get Policies	79
Get Policy	81
Create Policy	98
Update Policy	121
Delete Policy	140
Delete Policies	141
Zone API	142
Create Zone	143
Get Zones	144
Get Zone	146
Get Device Zones	148
Update Zone	149
Delete Zone	151
Threat API	152
Get Threats	153
Get Threat	156
Get Threat Devices	158

Cylance User API Guide, v2.0 rev34, December 2020 | 5

Get Threat Download URL	161
Memory Protection API	163
Get Memory Protection Events	164
Get Memory Protection Event	166
Memory Violation Types	168
Detection API	171
Get Detections	172
Get Detection	175
Get Recent Detections	182
Get Detections CSV	183
Get Detections By Severity	186
Update Detection	188
Delete Detection	190
Delete Detections	191
Package Deployment API	192
Create Package	193
Get Packages	195
Get Package	199
Delete Package	201
Create Package Execution	202
Get Package Executions	206
Get Package Execution	210
Delete Package Execution	212
Detection Rule API	215
Get Detection Rule List	216
Get Detection Rule CSV List	219
Get Detection Rule	220
Validate Detection Rule	224
Create Detection Rule	227
Update Detection Rule	232
Deactivate or Delete Detection Rule	237
Get Detection Rule Natural Language Representation	238
Get Detection Rule Counts	239
Detection Rule Sets	241

Cylance User API Guide, v2.0 rev34, December 2020 | 6

Get Detection Rule Set List	242
Get Detection Rule Set CSV List	245
Get Detection Rule Set	246
Create Detection Rule Set	250
Retrieve Default Detection Rule Set	255
Update Detection Rule Set	258
Delete Detection Rule Set	262
Delete Multiple Detection Rule Sets	263
Detection Exceptions	265
Get Detection Exceptions List	266
Get Detection Exception CSV List	268
Get Detection Exception Content	269
Create Detection Exception	271
Update Detection Exception	275
Deactivate / Delete Detection Exception	278
Device Commands	280
Device Commands	281
Lockdown Device Command	281
Get Device Lockdown History	283
Get Retrieved File Results	284
Request File Retrieval From Device	287
Check File Retrieval Status From Device	289
Focus View	292
Focus View	293
Get Focus View List	293
Search for Focus View Results	296
Request a Focus View	298
Get a Focus View Summary	301
Get Focus View Results	304
InstaQuery	306
InstaQuery	307
Get InstaQueries	307
Create InstaQuery	310
Get InstaQuery	314

Cylance User API Guide, v2.0 rev34, December 2020 | 7

Get InstaQuery Results	318
Archive InstaQuery	321
CylanceOPTICS Policy	323
CylanceOPTICS Policy	324
Get Detection Rule Sets to Policy Mapping	324
Get Detection Rule Set for a Policy	326
Update a Detection Rule Set in a Policy	327
API Tools	330
REST Clients	331
JSON Validators	331
Appendix	332
Find File Checksum	333
Windows	333
macOS	333
Linux	333
Threat Classifications	333
File Unavailable	334
Trusted - Local	334
PUP	334
Dual Use	335
Malware	336
Scope Values for Authentication Token	337
Legal Notice	340
Legal Notice	341

Cylance User API Guide, v2.0 rev34, December 2020 | 8

ApplicationManagement

- 9 -

Application Management

Cylance Console administrators can manage multiple API applications, including the access privileges to your Cylance Console data, CylancePROTECT and CylanceOPTICS.

To Add an Application

IMPORTANT: A tenant can have up to 10 Custom Applications.

1.Log in to the Cylance Console as an administrator. Only administrators can create an application integration.

2.Select Settings > Integrations.

3.Click Add Application.

4.Type an Application Name. This must be unique within your organization.

5.Select the access privileges for a Console data type. Not selecting any checkboxes for a data type means the application does not have access to that data type.

Cylance User API Guide, v2.0 rev34, December 2020 | 10

Figure 1: Configure Custom Application Settings

6.Click Save. The credentials to use for the application displays.

7.Copy and paste the Application ID and Application Secret to your API application. Or you can click OK to close the dialog box. You can view the Application ID and Application Secret from the Integrations page.

Note: There are some API operations listed in the Add Application matrix that can be enabled (Global List - Read and Modify; Policy - Write, Modify, and Delete) but are not available with the initial release. These API operations are currently under development and will be available in a future release.

Cylance User API Guide, v2.0 rev34, December 2020 | 11

Figure 2: View or Hide Custom Application Settings

Data Type	Description
CylanceOPTICS	The CylanceOPTICS Device Commands. Includes Device Lockdown (locking
Commands	a device, retrieving history) and File Retrieval (requesting, checking, and
	getting results).
CylanceOPTICS	The CylanceOPTICS Detection Events triggered by the Context Analysis
Detections	Engine (CAE). Enables further automation of analyzing, triaging, and
	responding to malicious or suspicious activity prevented or detected by
	CylanceOPTICS.
CylanceOPTICS	The CylanceOPTICS Detection Exceptions that adds exceptions to Detection
Exceptions	Rules.

CylanceOPTICS Focus The CylanceOPTICS Focus Views retrieves an information trail starting with Views the first event related to an artifact from an InstaQuery result or

CylancePROTECT event.

CylanceOPTICS	The CylanceOPTICS InstaQuery allows searching for system artifacts stored
InstaQueries	locally by CylanceOPTICS - files, registry key persistence points, processes,
	etc.
CylanceOPTICS	The CylanceOPTICS settings in a Policy. This requires the Policy settings to
Policies	also be enabled.
CylanceOPTICS	The CylanceOPTICS set of rules that is then applied to a Policy.
Rule Sets

CylanceOPTICS Rules The CylanceOPTICS Detection Rules that help monitor an organization for security threats or anomalous behavior.

Devices	Devices are systems with a Cylance Agent installed. You can get information
	about devices in your organization. You can also update (Modify) or remove
	(Delete) devices from your organization.
Global List	Global Lists include the Safe List and the Global Quarantine List. Each Global
	List operation has its own set of required and optional request fields.

Cylance User API Guide, v2.0 rev34, December 2020 | 12

Data Type	Description
Packages	The CylanceOPTICS packages to be sent and stored on devices.
Configuration	Note: CylanceOPTICS packages are not sent to devices by default.
	Devices must receive a command to download a package.

Packages Deployment The CylanceOPTICS packages to execute on devices.

Policies	Policies contain the protection settings applied to devices. Policies allow
	adding and removing devices instead of needing to manually update each
	device when you want to change the protection settings.
Threats	Threat Details provide information about a file as well as reference
	information about why a file is considered Safe or a Threat. Use the Threats
	request to get this information.
Users	Users have access to the data in the Console, based on the role assigned to
	the User. For example, an Administrator can see everything in the Console,
	while a User is limited to the zones to which the User is assigned.
Zones	Each device belongs to at least one Zone. Zones are similar to tags and
	assist in organizing your devices.

Privilege	Description
Delete	Ability to delete the data.
Modify	Ability to modify existing data. Also known as update.
Read	Ability to read data but cannot create, modify, or delete the data. Also known as list.
Write	Ability to add data to the Console. Also known as create.

To Edit an Application

1.Log in to the Cylance Console as an administrator. Only administrators can edit an application integration.

2.Select Settings > Integrations.

3.Click the Edit icon for the application you want to change.

Cylance User API Guide, v2.0 rev34, December 2020 | 13

Figure 3: Edit Custom Application

4. Edit the privileges, then click Save Changes.

Figure 4: Save Custom Application

To Delete an Application

1.Log in to the Cylance Console as an administrator. Only administrators can delete an application integration.

2.Select Settings > Integrations.

3.Click the Remove icon for the application you want to remove.

Figure 5: Remove Custom Application

4. Click Remove Application to confirm the deletion.

Cylance User API Guide, v2.0 rev34, December 2020 | 14

Figure 6: Remove Custom Application Confirmation Message

To Regenerate an Application Control

There may be times when it is necessary to regenerate the credentials for an Integration, like when credentials are compromised or stolen. For Cylance Integrations, regenerating credentials creates a new Application Secret; the Application ID remains unchanged.

Note: After regenerating credentials, you must update this information in the application used to generate the API access token.

1.Log in to the Cylance Console as an administrator. Only administrators can regenerate an application credential.

2.Select Settings > Integrations.

3.Click the down arrow to expand the information for the application for which you want to regenerate credentials.

Table 1: Regenerate Custom Application Credentials

4.Click Regenerate Credentials. A confirmation message appears.

5.Click Yes, Regenerate to confirm regenerating the credentials.

Cylance User API Guide, v2.0 rev34, December 2020 | 15

Figure 7: Regenerate Custom Application Credentials Confirmation Message

Copy Tenant ID

The Tenant ID is required for authorization. You can copy your Tenant ID from the Integrations page.

Figure 8: Copy Tenant ID

API in Audit Logs

The API calls listed below are included in the Console Audit Log (My Account > Audit Log) when something is created or updated. In the Audit Log, the "Who" field displays the Application Name, not the username.

nPolicy: Create, Update, or Delete

nGlobal List: Add or Delete

nZone: Create, Update, or Delete

Cylance User API Guide, v2.0 rev34, December 2020 | 16

nTenant User: Create, Update, or Delete

nDevice: Update Device, Update Device Threat, or Delete Device

Cylance User API Guide, v2.0 rev34, December 2020 | 17

RESTful API

- 18 -

Cylance provides RESTful APIs for registered organizations to manage their resources. To access the Cylance API resources, the client will need to follow the authentication and authorization flow as defined below. This requires the client to send a request to the Auth endpoint, which will return an access token that the client will use for calling all other endpoints.

Note: Cylance supports Cylance API resources, including helping users troubleshoot Cylance API requests. Cylance does not write or train users on how to create scripts or code (like using Python).

Authentication and Authorization

Application

An Application acts as an integration point between the client system and the Cylance API. Through the Application, the client system is granted temporary access to act upon resources. Actions will be limited by the scopes associated to the Application itself, as defined in the

"Application Management" on page 10 section.

Service Endpoint

The service endpoint address can contain a region code to identify the set of servers to which your organization belongs.

Example for Europe - Central: http://protectapi-euc1.cylance.com/devices/v2

Note: North America and US Government have a different format. See Service Endpoint column below for examples.

Region	Code	Service Endpoint with Region Code
Asia-Pacific - North	apne1	https://protectapi-apne1.cylance.com/
Asia-Pacific - Southeast	au	https://protectapi-au.cylance.com/
Europe - Central	euc1	https://protectapi-euc1.cylance.com/
North America		https://protectapi.cylance.com/
South America	sae1	https://protectapi-sae1.cylance.com/
US Government	us	https://protectapi.us.cylance.com/

Cylance User API Guide, v2.0 rev34, December 2020 | 19

Authentication

During the step which a client system requests access prior to using Cylance Resources, there is an independent Web API that will handle the Authentication process and grant access to the client system. A token based authentication approach is being taken as a means of data transportation between the parties. Cylance has adopted JWT (RFC 7519) as the token format for its simplicity as well as its capabilities for digital signature.

The following actors exist in the Authentication workflow:

nAuthentication Token: Created and signed by the client system to perform an Authentication request, it is in this request where the Application is indicated.

nAuthentication Endpoint: Part of the Cylance Auth Web API which will handle the authentication requests coming from client systems, there will be a particular endpoint to handle JWT tokens.

nAccess Token: If authentication is successful and the client system is granted access to the requested application, a token representing this identity and some key attributes will be returned as a JWT token.

Authentication Token

The Authentication Token contains the ID of the Application to which a client system is requesting access. The Application contains two attributes: Application ID and Application Secret, the latter is cryptographic nonce used to sign the token, thus ensuring the authenticity of the caller and therefore, it must be shared between client and server. The Authentication endpoint has a mechanism to verify the signature and eventually proceed to grant access to the Application, if the client request is indeed allowed.

The client will create the Authentication token by indicating the Application ID as a claim and sign it using the Application Secret.

The Authentication Token must have the following claims. All are registered and conform to the JWT standard.

Claim

Type

Description

Registered Claims

exp NumericDate Date and time when the Token expires and is no longer valid for processing. This is Unix epoch time in seconds.

Note: The longest time-span honored by the service is 30 minutes from the value specified in the iat claim. Specifying a longer time-span will result in an HTTP 400 (Bad Request) response from the server.

Cylance User API Guide, v2.0 rev34, December 2020 | 20

Claim	Type	Description
iat	NumericDate	Time when the token was issued. This is Unix epoch time in seconds.
iss	StringOrUri	Represents the principal issuing the token, which is http://cylance.com.
jti	String	Unique ID for the token, which can be used to prevent reply attacks.
sub	StringOrUri	Principal subject to the claim. In our case, this would hold our Application
		ID.
		Custom Claims
scp	String	Comma delimited scopes requested. This claim is optional.
tid	String	Tenant ID (available on the Integrations page in the Console).
Example:
	Authentication Token - Adding Required Token Claims
DateTime now = DateTime.UtcNow;
long unixTimestamp = now.ToUnixTimestamp();

token.Claims.Add("iss", "http://cylance.com"); token.Claims.Add("iat", now.ToUnixTimestamp();); token.Claims.Add("exp", now.AddMinutes(1).ToUnixTimestamp()); token.Claims.Add("sub", "k45f6798092hjdhs836h"); token.Claims.Add("jti", "k45f6798092hjdhs836h+d82c7976-ef46-47b6- 80ce-4dda3c91bba3");

token.Claims.Add("tid", "f00e9987-ee61-57b7-80cf-5eeb3d02ccb4”); token.claims.Add(“scp”, “policy:create, policy:list, policy:read, policy:update”)

Generating the Authentication and Access Tokens

The Authentication Token can be generated using Python. You can use the Python example below, adding the required token claims that you need.

Note: Cylance Support does not provide assistance with installing non-Cylance programs (like Python) or security (lke PyJWT). Cylance does have a knowledge base article with an example for installing Python and PyJWT on Windows; this example is provided AS-IS and there is no guarantee the example will work in your environment.

Software Requirements:

nPython 3.7 (latest version recommended)

nPyJWT package (pip install PyJWT)

Cylance User API Guide, v2.0 rev34, December 2020 | 21

n Requests package (pip install requests)

Notes:

nCopying the Python Example from the PDF requires proper formatting in Python due to the extra line breaks that can cause an error. Use the Python and PyJWT on Windows knowledge base article to copy the example.

nExample using C# are available upon request.

Python Example

#WARNING: Copying this example from the PDF requires proper

#formatting in Python due to the extra lines breaks that

#can cause an error.

#RECOMMENDED: Use the Python and PyJWT on Windows knowledge base

#article to copy the example.

import jwt # PyJWT version 1.7.1 as of the time of authoring. import uuid

import requests # requests version 2.22.0 as of the time of authoring import json

from datetime import datetime, timedelta

# 30 minutes from now timeout = 1800

now = datetime.utcnow()

timeout_datetime = now + timedelta(seconds=timeout) epoch_time = int((now - datetime(1970, 1, 1)).total_seconds())

epoch_timeout = int((timeout_datetime - datetime(1970, 1, 1)).total_ seconds())

jti_val = str(uuid.uuid4())

tid_val = "" # The tenant's unique identifier. app_id = "" # The application's unique identifier.

app_secret = "" # The application's secret to sign the auth token with.

AUTH_URL = "https://protectapi.cylance.com/auth/v2/token"

claims = {

"exp": epoch_timeout, "iat": epoch_time,

"iss": "http://cylance.com", "sub": app_id,

"tid": tid_val, "jti": jti_val

#The following is optional and is being noted here as an example on how one can restrict

#the list of scopes being requested

#"scp":

Cylance User API Guide, v2.0 rev34, December 2020 | 22

Python Example

["policy:create","policy:list","policy:read","policy:update"]

}

encoded = jwt.encode(claims, app_secret, algorithm='HS256').decode ('utf-8')

print ('auth_token:\n' + encoded + "\n")

payload = {"auth_token": encoded}

headers = {"Content-Type": "application/json; charset=utf-8"} resp = requests.post(AUTH_URL, headers=headers, data=json.dumps (payload))

print("http_status_code: " + str(resp.status_code)) print("access_token:\n" + json.loads(resp.text)['access_token'] + "\n")

Token Lifecycle

An Authentication token should be used only once per request. This means the same token should not be usable for more than one request to prevent impersonation attempts. The jti attribute uniquely identifies the token. It can be used to keep track of all the tokens and prevent them from being reused. To ensure that the authentication token can be used only once, an expiration is enforced on the token. This means the token is usable within a few minutes or less.

Request / Response Model

HTTP Method POST

Endpoint /auth/v2/token

Example: https://protectapi.cylance.com/auth/v2/token

Request Accept: application/json

Headers

Content-Type: application/json

Authorization: Bearer <JWT Token returned by Auth API> with the user:create scope encoded.

Request {

"title": "Authoriztion Request",

"type": "object"

"properties": {

"auth_token": {

"type": ""

"description": "token representing authorization request"

}

Cylance User API Guide, v2.0 rev34, December 2020 | 23

},

"request": ["auth_token"]

}

Authorization

In response to the Authentication request, the client will receive a response that contains at least the Access Token. The access token will contain the Scopes that will dictate what can or cannot be done. This token is signed by the server and the client will merely echo it on every request as it tries to access Resources.

The access token represents the identity of the requester as well as some attributes like Scopes. This token will have an expiration and should be sent on every request in the Authorization Request Header. Failing to do so will result in an HTTP/1.1 401 Unauthorized response. Should the token be provided and prove to be legitimate but the server finds the action the caller is trying to attempt is not allowed (found in the scopes granted), an HTTP/1.1 403 Forbidden will be returned.

Access Token

The Access token represents a grant to access Cylance Resources. It contains information about the identity of the caller (Application) as well as control information form the Token itself, for instance, date it was issued and expiration. This token is also responsible for holding all Scopes that would be used by our system to validate actions attempted to be taken against Cylance Resources.

There is an expiration associated to this Token. The expiration time will be set during token creation on the server side. After the token expires, the server will respond with HTTP/1.1 401 Unauthorized indicating to the caller to authenticate again with a new access token.

Response Status Codes

Each API request will receive a response with a JSON payload and a standard HTTP status code.

Note: Some API request sections include additional response status descriptions (specific to that request) to help you troubleshoot issues.

Status	Description
Code
200 - OK	A successful call and operation. The response payload will be JSON, structured
	according to the nature of the request.

Cylance User API Guide, v2.0 rev34, December 2020 | 24

Status		Description
Code
400	- Bad	There was a problem with the structure of the request or the payload. If determinable,
Request		the response payload will identify the failure in the request. A common case of this type
		of error is malformed JSON in the request body. A JSON validator can be used to
		troubleshoot these issues.
401	-	Invalid credentials were passed or some other failure in authentication.
Unauthorized
403	-	Request has been successfully authenticated, but authorization to access the
Forbidden		requested resource was not granted.
404	- Not	A request was made for a resource that doesn't exist. Common causes are either an
Found		improperly formed URL or an invalid API key.
409	- Conflict	A request was made to create or update an aspect of the resource that conflicts with
		another. The most common reason for this code is a Tenant name or User email that is
		already in use.
500	- Internal	A catch-all code response for any unhandled error that has occurred on the server.
Server Error		Contact Cylance Support for help with this issue.
501	- Not	A request was made against a resource with an operation that has yet to be
Implemented		implemented. Such operations should be identified accordinly in documentation.
Other		Contact Cylance Support if you encounter any status codes that are not on this list.

API Rate Limit

The rate limiting for API endpoints is 100,000 requests per day, or about 70 requests per minute. If a tenant exceeds these limits, they will receive a 429 error - Too Many Requests. If you encounter a 429 error, wait 60 seconds before retrying the API request.

The purpose of a rate limit is to maintain a good user experience for all API users. Without a rate limit, API endpoints can flood the server with requests that overwhelm the system and negatively impact all users.

About Device ID

When attempting to query a CylanceOPTICS API call that utilizes a device ID value, be aware of the following:

The format for the CylanceOPTICS API device ID value should be:

CylanceOPTICS Example:

n 45E07F34E76B4A9EB167D6D0C510D6BA (upper case without dashes)

Cylance User API Guide, v2.0 rev34, December 2020 | 25

Passing the device ID value as the CylancePROTECT format will return an HTTP 200 status, as if the call was successful, but you will receive an incorrect response.

CylancePROTECT Example:

n 45e07f34-e76b-4a9e-b167-d6d0c510d6ba (lower case with dashes)

To obtain the device ID, you must query the CylancePROTECT API, then format the device ID to match the CylanceOPTICS format (see example above).

This query can be found in the Device API section of this document. Use the Get Devices and Get Device requests from the guide. The device ID value is the field titled "id".

About Zone ID

When attempting to query a CylanceOPTICS API call that utilizes a zone ID value, be aware of the following:

The format for the CylanceOPTICS API zone ID value should be:

CylanceOPTICS Example:

n D27FF5C45C0D4F56A00DA1FB297E440E (upper case without dashes)

Passing the zone ID value as the CylancePROTECT format will return an HTTP 200 status, as if the call was successful, but you will receive an incorrect response.

CylancePROTECT Example:

n d27ff5c4-5c0d-4f56-a00d-a1fb297e440e (lower case with dashes)

To obtain the zone ID, you must query the CylancePROTECT API, then format the zone ID to match the CylanceOPTICS format (see example above).

This query can be found in the Zone API section of this document. Use the Get Zones and Get Zone requests from the guide.

Cylance User API Guide, v2.0 rev34, December 2020 | 26

UserAPI

- 27 -

Create User

Create (add) a new Console user. This requires a unique email address for the user being

created.

Service Endpoint:

n /users/v2

Example: https://protectapi.cylance.com/users/v2

Method:

n HTTP/1.1 POST

Request Header:

nAccept: application/json

nContent-Type: application/json

nAuthorization: Bearer <JWT Token returned by Auth API> with the user:create scope encoded.

Request:

{

"email": "[e-mail]",

"user_role": "00000000-0000-0000-0000-000000000001", "first_name": "Test",

"last_name": "User", "zones": [

{

"id": "d27ff5c4-5c0d-4f56-a00d-a1fb297e440e", "role_type": "00000000-0000-0000-0000-000000000002"

}

]

}

Response:

201 Created

{

"id": "a2c0ac7a-a63d-4583-b646-ae10db9c9768", "tenant_id": "4b1640d2-d563-41cf-94a7-0da1dca6aa98", "first_name": "Test",

"last_name": "User",

"email": "[e-mail]", "has_logged_in": false,

"role_type": "00000000-0000-0000-0000-000000000001", "role_name": "User",

Cylance User API Guide, v2.0 rev34, December 2020 | 28

"default_zone_role_type": "00000000-0000-0000-0000-000000000000",

"default_zone_role_name": "None",

"zones": [

{

"id": "d27ff5c4-5c0d-4f56-a00d-a1fb297e440e", "role_type": "00000000-0000-0000-0000-000000000002"

}

]

"date_last_login": null, "date_email_confirmed": null, "date_created": "2019-09-13T22:33:26.098Z", "date_modified": "2019-09-13T22:33:26.098Z"

}

400 Bad Request - Returned for the following reasons:

nThe User create request was empty.

nThe Tenant ID cannot be retrieved from the JWT Token.

nThe User's email address specified is not a proper email address.

nThe User application role specified is not one of the accepted values.

nThe zones array is empty when the User application role is not Administrator.

nThe email provided is already in use.

401 Unauthorized - The JWT Token is not specified, has expired, or is otherwise invalid. 403 Forbidden - The JWT Token did not contain the proper scope to perform this action. 500 Internal Server Error - An unforeseeable error has occurred.

Request JSON Schema Descriptions

Field Name		Description
email	The user's email address. This must be unique.
first_name	The user's first name. Maximum of 64 characters.
last_name	The user's last name. Maximum of 64 characters.
user_role	The user's role in the Console.
	n	User: 00000000-0000-0000-0000-000000000001
	n	Administrator: 00000000-0000-0000-0000-000000000002
	n	Read-Only: 00000000-0000-0000-0000-000000000003
zones	The zones to which the user has access. This is an array of
	elements.
	n	id: The unique identifier for the zone.
	n	role_type: The user's role for this particular zone.

Cylance User API Guide, v2.0 rev34, December 2020 | 29

Field Name

Description

•Zone Manager: 00000000-0000-0000-0000- 000000000001

•User: 00000000-0000-0000-0000-000000000002

Note: If the user is an Administrator, the zones array is not required.

Note: To create a Zone Manager, set the user_role to User and assign a zone or zones to the User via the Zones parameter. Setting the user_role to Read-Only and using the Zones parameter will result in a bad request error.

Response JSON Schema Descriptions

	Field		Description
	Name
	date_	The date and time (in UTC) the Console user was created.
	created
	date_	The date and time (in UTC) when the user confirmed the email provided. This
	email_	should be null because the user account was recently created.
	confirmed
	date_	The date and time (in UTC) the user last logged in to the Console. This should be
	last_login	null because the user account was recently created.
	date_	The date and time (in UTC) the Console user information was last updated.
	modified
	default_	The name of the role for the user in the zone.
	zone_
	role_
	name
	default_	The unique identifier for the user's default role when assigned to a zone.
	zone_	n	None: 00000000-0000-0000-0000-000000000000
	role_type
			Zone Manager: 00000000-0000-0000-0000-000000000001
		n
		n	User: 00000000-0000-0000-0000-000000000002
	email	The user's email address.
	first_	The user's first name.
	name
	has_	This should be false because the user account was recently created.
	logged_
	in
	id	The user's unique identifier for the Console.
	last_	The user's last name.

Cylance User API Guide, v2.0 rev34, December 2020 | 30