BlackBerry CylancePROTECT, CylanceOPTICS User Manual
Cylance® API
User API v2.0 Guide
Product:CylancePROTECT® and CylanceOPTICS
Document:Cylance APIGuide. 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.
.
Table of Contents
- 3 -
Contents
Table of Contents
Application Management
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
Authentication and Authorization 19
Application 19
Service Endpoint 19
Authentication 20
Authentication Token 20
Generating the Authentication and Access Tokens 21
Token Lifecycle 23
3
9
18
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
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
27
42
Cylance User APIGuide, 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
Get Global List 72
Add to Global List 74
Delete From Global List 76
Policy API
Get Policies 79
Get Policy 81
Create Policy 98
Update Policy 121
Delete Policy 140
Delete Policies 141
Zone API
Create Zone 143
Get Zones 144
Get Zone 146
Get Device Zones 148
Update Zone 149
71
78
142
Delete Zone 151
Threat API
Get Threats 153
Get Threat 156
Get Threat Devices 158
Cylance User APIGuide, v2.0 rev34, December 2020 | 5
152
Get Threat Download URL 161
Memory Protection API
Get Memory Protection Events 164
Get Memory Protection Event 166
Memory Violation Types 168
Detection API
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
Create Package 193
Get Packages 195
Get Package 199
163
171
192
Delete Package 201
Create Package Execution 202
Get Package Executions 206
Get Package Execution 210
Delete Package Execution 212
Detection Rule API
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
215
241
Cylance User APIGuide, 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
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
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
Focus View 293
Get Focus View List 293
265
280
292
Search for Focus View Results 296
Request a Focus View 298
Get a Focus View Summary 301
Get Focus View Results 304
InstaQuery
InstaQuery 307
Get InstaQueries 307
Create InstaQuery 310
Get InstaQuery 314
Cylance User APIGuide, v2.0 rev34, December 2020 | 7
306
Get InstaQuery Results 318
Archive InstaQuery 321
CylanceOPTICS Policy
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
REST Clients 331
JSON Validators 331
Appendix
Find File Checksum 333
Windows 333
macOS 333
Linux 333
Threat Classifications 333
File Unavailable 334
Trusted - Local 334
PUP 334
323
330
332
Dual Use 335
Malware 336
Scope Values for Authentication Token 337
Legal Notice
Legal Notice 341
340
Cylance User APIGuide, v2.0 rev34, December 2020 | 8
Application Management
- 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 APIGuide, 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 APIGuide, v2.0 rev34, December 2020 | 11
Figure 2: View or Hide Cust om Application Settings
Data Type Description
CylanceOPTICS
Commands
CylanceOPTICS
Detections
CylanceOPTICS
Exceptions
CylanceOPTICSFocus
Views
CylanceOPTICS
InstaQueries
CylanceOPTICS
Policies
CylanceOPTICS
RuleSets
The CylanceOPTICS Device Commands. Includes Device Lockdown (locking
a device, retrieving history) and File Retrieval (requesting, checking, and
getting results).
The CylanceOPTICS Detection Events triggered by the Context Analysis
Engine (CAE). Enables further automation of analyzing, triaging, and
responding to malicious or suspicious activity prevented or detected by
CylanceOPTICS.
The CylanceOPTICS DetectionExceptions that adds exceptions to Detection
Rules.
The CylanceOPTICS Focus Views retrieves an information trail starting with
the first event related to an artifact from an InstaQuery result or
CylancePROTECT event.
The CylanceOPTICS InstaQuery allows searching for system artifacts stored
locally by CylanceOPTICS - files, registry key persistence points, processes,
etc.
The CylanceOPTICS settings in a Policy. This requires the Policy settings to
also be enabled.
The CylanceOPTICS set of rules that is then applied to a Policy.
CylanceOPTICS Rules The CylanceOPTICSDetection 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.
GlobalList 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 APIGuide, v2.0 rev34, December 2020 | 12
Data Type Description
Packages
Configuration
Packages Deployment The CylanceOPTICS packages to execute on devices.
Policies Policies contain the protection settings applied to devices. Policies allow
Threats Threat Details provide information about a file as well as reference
Users Users have access to the data in the Console, based on the role assigned to
Zones Each device belongs to at least one Zone.Zones are similar to tags and
The CylanceOPTICS packages to be sent and stored on devices.
Note: CylanceOPTICS packages are not sent to devices by default.
Devices must receive a command to download a package.
adding and removing devices instead of needing to manually update each
device when you want to change the protection settings.
information about why a file is considered Safe or a Threat. Use the Threats
request to get this information.
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.
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 APIGuide, v2.0 rev34, December 2020 | 13
Figure 3: Edit Custom Applicat ion
4. Edit the privileges, then click Save Changes.
Figure 4: Save Cust om 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 APIGuide, 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 APIaccess 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 APIGuide, 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.
n
Policy:Create, Update, or Delete
n
Global List:Add or Delete
n
Zone:Create, Update, or Delete
Cylance User APIGuide, v2.0 rev34, December 2020 | 16
n
Tenant User:Create, Update, or Delete
n
Device:Update Device, Update Device Threat, or Delete Device
Cylance User APIGuide, v2.0 rev34, December 2020 | 17
RESTful API
- 18 -
Cylance provides RESTful APIs for registered organizations to manage their resources. To
access the CylanceAPI 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 CylanceAPIresources, including helping users troubleshoot Cylance
APIrequests. 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 page10 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 USGovernment have a different format. See Service Endpoint column
below for examples.
Region Code Service Endpoint with Region Code
Asia-Pacific - North apne1
Asia-Pacific - Southeast au
Europe - Central euc1
North America
South America sae1
USGovernment us
https://protectapi-apne1.cylance.com/
https://protectapi-au.cylance.com/
https://protectapi-euc1.cylance.com/
https://protectapi.cylance.com/
https://protectapi-sae1.cylance.com/
https://protectapi.us.cylance.com/
Cylance User APIGuide, 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:
n
Authentication Token:Created and signed by the client system to perform an
Authentication request, it is in this request where the Application is indicated.
n
Authentication 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.
n
Access 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
JWTstandard.
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 APIGuide, v2.0 rev34, December 2020 | 20
Claim Type Description
iat NumericDate
iss StringOrUri
jti String
sub StringOrUri
Time when the token was issued. This is Unix epoch time in seconds.
Represents the principal issuing the token, which is
Unique ID for the token, which can be used to prevent reply attacks.
Principal subject to the claim. In our case, this would hold our Application
ID.
http://cylance.com
Custom Claims
scp String
tid String
Comma delimited scopes requested. This claim is optional.
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-47b680ce-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:
n Python 3.7 (latest version recommended)
n PyJWT package (pip install PyJWT)
Cylance User APIGuide, v2.0 rev34, December 2020 | 21
n Requests package (pip install requests)
Notes:
n Copying 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.
n Example using C# are available upon request.
PythonExample
# 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 APIGuide, v2.0 rev34, December 2020 | 22
PythonExample
["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
HTTPMethod POST
Endpoint /auth/v2/token
Example:https://protectapi.cylance.com/auth/v2/token
Request
Headers
Request
Accept: application/json
Content-Type: application/json
Authorization:Bearer <JWTToken returned by AuthAPI>with the user:create
scope encoded.
{
"title":"Authoriztion Request",
"type": "object"
"properties": {
"auth_token": {
"type": ""
"description": "token representing authorization request"
}
Cylance User APIGuide, 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 APIrequest will receive a response with a JSON payload and a standard HTTPstatus
code.
Note: Some API request sections include additional response status descriptions (specific to that
request) to help you troubleshoot issues.
Status
Code
Description
200 - OK A successful call and operation. The response payload will be JSON, structured
according to the nature of the request.
Cylance User APIGuide, v2.0 rev34, December 2020 | 24
Status
Code
Description
400 - Bad
Request
401 Unauthorized
403 Forbidden
404 - Not
Found
409 - Conflict A request was made to create or update an aspect of the resource that conflicts with
500 - Internal
Server Error
501 - Not
Implemented
Other Contact Cylance Support if you encounter any status codes that are not on this list.
There was a problem with the structure of the request or the payload. If determinable,
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.
Invalid credentials were passed or some other failure in authentication.
Request has been successfully authenticated, but authorization to access the
requested resource was not granted.
A request was made for a resource that doesn't exist. Common causes are either an
improperly formed URL or an invalid APIkey.
another. The most common reason for this code is a Tenant name or User email that is
already in use.
A catch-all code response for any unhandled error that has occurred on the server.
Contact Cylance Support for help with this issue.
A request was made against a resource with an operation that has yet to be
implemented. Such operations should be identified accordinly in documentation.
API Rate Limit
The rate limiting for APIendpoints 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 APIusers. Without a
rate limit, APIendpoints can flood the server with requests that overwhelm the system and
negatively impact all users.
About Device ID
When attempting to query a CylanceOPTICS APIcall that utilizes a device ID value, be aware
of the following:
The format for the CylanceOPTICS APIdevice ID value should be:
CylanceOPTICS Example:
n 45E07F34E76B4A9EB167D6D0C510D6BA (upper case without dashes)
Cylance User APIGuide, v2.0 rev34, December 2020 | 25
Passing the device ID value as the CylancePROTECT format will return an HTTP200 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 APIcall that utilizes a zone ID value, be aware of
the following:
The format for the CylanceOPTICS APIzone ID value should be:
CylanceOPTICS Example:
n D27FF5C45C0D4F56A00DA1FB297E440E (upper case without dashes)
Passing the zone ID value as the CylancePROTECT format will return an HTTP200 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 APIGuide, v2.0 rev34, December 2020 | 26
User API
- 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:
n Accept:application/json
n Content-Type:application/json
n Authorization:Bearer <JWTToken returned by AuthAPI> with the user:create scope
encoded.
Request:
{
"email": "testuser@email.com",
"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": "testuser@email.com",
"has_logged_in": false,
"role_type": "00000000-0000-0000-0000-000000000001",
"role_name": "User",
Cylance User APIGuide, 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:
n The User create request was empty.
n The Tenant ID cannot be retrieved from the JWTToken.
n The User's email address specified is not a proper email address.
n The User application role specified is not one of the accepted values.
n The zones array is empty when the User application role is not Administrator.
n The email provided is already in use.
401 Unauthorized - The JWTToken is not specified, has expired, or is otherwise invalid.
403 Forbidden - The JWTToken did not contain the proper scope to perform this action.
500 Internal Server Error - An unforeseeable error has occurred.
Request JSONSchema 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 APIGuide, v2.0 rev34, December 2020 | 29
Field Name Description
l Zone Manager: 00000000-0000-0000-0000-
000000000001
l 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 JSONSchema Descriptions
Field
Name
date_
created
date_
email_
confirmed
date_
last_login
date_
modified
default_
zone_
role_
name
default_
zone_
role_type
Description
The date and time (in UTC) the Console user was created.
The date and time (inUTC) when the user confirmed the email provided. This
should be null because the user account was recently created.
The date and time (in UTC)the user last logged in to the Console. This should be
null because the user account was recently created.
The date and time (in UTC) the Console user information was last updated.
The name of the role for the user in the zone.
The unique identifier for the user's default role when assigned to a zone.
n None: 00000000-0000-0000-0000-000000000000
n Zone Manager:00000000-0000-0000-0000-000000000001
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 APIGuide, v2.0 rev34, December 2020 | 30
Loading...