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 -
Cylance Console administrators can manage multiple API applications, including the access privileges to your Cylance Console data, CylancePROTECT and CylanceOPTICS.
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. |
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
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
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
The Tenant ID is required for authorization. You can copy your Tenant ID from the Integrations page.
Figure 8: Copy Tenant ID
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
- 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).
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.
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
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.
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”)
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")
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.
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"]
}
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.
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.
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. |
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.
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".
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 (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": "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 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 |
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 |
|
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