Generate an API key and make your first API call.
Before you can begin using Cortex XSIAM APIs, you must generate the following items from Cortex XSIAM:
Value | Description |
---|---|
API Key | The API Key is your unique identifier used as the Depending on your desired security level, you can generate two types of API keys, Advanced or Standard, from your Cortex XSIAM app. |
API Key ID | The API Key ID is your unique token used to authenticate the API Key. The header used when running an API call is |
FQDN | The FQDN is a unique host and domain name associated with each tenant. When you generate the API Key and Key ID, you are assigned an individual FQDN. |
Cortex XSIAM API URIs are made up of your unique FQDN, the API name, and the endpoint.
For example, https://api-{fqdn}/public_api/v1/{name of api}/{name of call}/
.
The following steps describe how to generate the necessary key values.
Get your Cortex XSIAM API Key.
In Cortex XSIAM , navigate to → → → .
Select + New Key.
Choose the type of API Key you want to generate based on your desired security level: Advanced or Standard.
The Advanced API key hashes the key using a nonce, a random string, and a timestamp to prevent replay attacks. cURL does not support this but is suitable with scripts. Use the Advanced Key Python 3 Example to create the advanced API authentication token.
If you want to define a time limit on the API key authentication, mark Enable Expiration Date and select the expiration date and time.
Navigate to Expiration Time field for each API key. In addition, Cortex XSIAM displays the API Key Expiration notification in the Notification Center one week and one day prior to the defined expiration date.
→ → → to track theProvide a comment that describes the purpose of the API key, if desired.
Select the desired level of access for this key.
You can select from the list of existing Roles, or you can select Custom to set the permissions on a more granular level. Roles are available according to what was defined in the hub as described in the Manage Roles section of the Cortex XSIAM Administrator’s Guide.
Generate the API Key.
Copy the API key, and then click Done. This value represents your unique
Authorization:{key}
.Caution
You will not be able to view the API Key again after you complete this step so ensure that you copy it before closing the notification.
Get your Cortex XSIAM API Key ID.
In the API Keys table, locate the ID field.
Note your corresponding ID number. This value represents the
x-xdr-auth-id:
token.{key_id}
Get your FQDN.
Select your API key and click Copy URL .
You can use the CURL Example URL to run the APIs.
Make your first API call.
The following examples vary depending on the type of key you select.
You can test authentication with Advanced API keys using the provided Python 3 example. With Standard API keys, use either the cURL example or the Python 3 example. Don’t forget to replace the example variables with your unique API key, API key ID, and FQDN tenant ID.
After you verify authentication, you can begin making API calls.
Standard Key cURL Example
curl -X POST https://api-{fqdn}/public_api/v1/{name of api}/{name of call}/ -H "x-xdr-auth-id:{key_id}" -H "Authorization:{key}" -H "Content-Type:application/json" -d '{}'
Standard Key Python 3 Example
import requests def test_standard_authentication(api_key_id, api_key): headers = { "x-xdr-auth-id": str(api_key_id), "Authorization": api_key } parameters = {} res = requests.post(url="https://api-{fqdn}/public_api/v1/{name of api}/{name of call}", headers=headers, json=parameters) return res
Advanced Key Python 3 Example
import requests from datetime import datetime, timezone import secrets import string import hashlib import requests def test_advanced_authentication(api_key_id, api_key): # Generate a 64 bytes random string nonce = "".join([secrets.choice(string.ascii_letters + string.digits) for _ in range(64)]) # Get the current timestamp as milliseconds. timestamp = int(datetime.now(timezone.utc).timestamp()) * 1000 # Generate the auth key: auth_key = "%s%s%s" % (api_key, nonce, timestamp) # Convert to bytes object auth_key = auth_key.encode("utf-8") # Calculate sha256: api_key_hash = hashlib.sha256(auth_key).hexdigest() # Generate HTTP call headers headers = { "x-xdr-timestamp": str(timestamp), "x-xdr-nonce": nonce, "x-xdr-auth-id": str(api_key_id), "Authorization": api_key_hash } parameters = {} res = requests.post(url="https://api-{fqdn}/public_api/v1/{name of api}/{name of call}", headers=headers, json=parameters) return res
Note
There is a limit of 10 API requests per second for each tenant. This includes all endpoints. Sending more than 10 requests per second can result in the following error: "Too many requests."