Get Started with APIs

What you need to run Cortex XDR APIs.
Before you can begin using
Cortex
XDR
APIs, you must generate the following items from the
Cortex
XDR
app:
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
, from your
Cortex
XDR
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
"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.
Cortex
XDR
API URIs are made up of your unique FQDN, the API name, and name of call. 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.
  1. Get your
    Cortex
    XDR
    API Key.
    1. In
      Cortex
      XDR
      , navigate to
      Settings
      Configurations
      Integrations
      API Keys
      .
    2. Select
      + New Key
      .
    3. 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 useing a nonce, a random string, and a timestamp to prevent replay attacks. cURL does not support this but is suitable with scripts. Use the to create the advanced API authentication token.
      To integrate with Cortex XSOAR you must generate an Advanced Key.
    4. 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
      Settings
      Configurations
      Integrations
      API Keys
      to track the
      Expiration Time
      field for each API key. In addition,
      Cortex
      XDR
      displays a API Key Expiration notification in the Notification Center one week and one day prior to the defined expiration date.
    5. Provide a comment that describes the purpose for the API key, if desired.
    6. 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 what was defined in the hub as described in the Manage Roles section of the
      Cortex
      XDR
      Administrator’s Guide.
    7. Generate
      the API Key.
    8. Copy the API key, and then click
      Done
      . This value represents your unique
      Authorization:{key}
      .
      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.
  2. Get your
    Cortex
    XDR
    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.
  3. Get your FQDN.
    1. Right-click your API key and select
      View Examples
      .
    2. Copy the
      CURL Example
      URL. The example contains your unique FQDN:
      https://api-{fqdn}/public_api/v1/{name of api}/{name of call}/
    You can use the
    CURL Example
    URL to run the APIs.
  4. 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

Recommended For You