Cortex XSOAR API

Generate API keys and make API calls in Cortex XSOAR 8 SaaS.

Before you can begin using Cortex XSOAR APIs, you must generate the following items from Cortex XSOAR:

Value	Description
API Key	The API Key is your unique identifier used as the Authorization:{key} header required for authenticating API calls. Depending on your desired security level, you can generate two types of API keys, Advanced or Standard. The Advanced key hashes the key using a nonce, a random string, and a timestamp to prevent replay attacks. cURL does not support this but it can be used with scripts.
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 x-xdr-auth-id:{key_id}.
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.

The API is documented in detail in the Cortex XSOAR API Reference Guide.

Cortex XSOAR API URIs comprise of your unique FQDN, the API name, and the name of the call. For example, https://api-{fqdn}/xsoar/{name of api}/{name of call}/.

The following steps describe how to generate the necessary key values.

Task 1. Create an API key

1. Select Settings & Info → Settings → Integrations → API Keys → New Key.
2. Select the type of API Key you want to generate based on your desired security level: Advanced or Standard.
3. To define a time limit on the API key authentication, mark Enable Expiration Date and select the expiration date and time.

   You can view the Expiration Time field for each API key at Settings & Info → Settings → Integrations → API Keys . In addition, Cortex XSOAR displays an API Key Expiration notification in the Notification Center one week and one day before the defined expiration date.
4. (Optional) Provide a comment that describes the purpose of the API key.
5. Expand each area to select the desired level of access for this key.

   Select a role from the list of existing Roles, or a Custom Role from the list of previously defined roles to set the permissions on a more granular level. You can select multiple roles.
6. Generate the API Key.
7. Copy the API key, and then click Close. This value represents your unique Authorization:{key}.

   Caution

   You can't view the API Key again after you complete this step so ensure that you copy it before closing the notification.

Task 2. Get your Cortex XSOAR API key ID

1. In the API Keys table, locate the ID field.
2. Note your corresponding ID number. This value represents the x-xdr-auth-id:{key_id} token.

Task 3 Get your FQDN

1. Go to Settings & Info → Settings → Integrations → API Keys.
2. Click Copy API URL

   Your FQDN is saved in the clipboard. You must use the FQDN as part of the URL in every API call. For example: https://api-company.us.com/xsoar/public/v1/{endpoint_path}/

Task 3 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.

Example: Create an incident - Standard key cURL example

curl -X POST https://api-company.us.com/xsoar/public/v1/incident
-H "x-xdr-auth-id:{api_key_id}" 
-H "Authorization:{api_key}" 
-H "Content-Type:application/json" 
--data '{
"details": "My test incident",
"name": "My test incident",
"severity": 2,
"type": "Unclassified"
}'