Get Started with APIs - Administrator Guide - 8 - Cortex XSOAR - Cortex - Security Operations

Cortex XSOAR Administrator Guide

Product
Cortex XSOAR
Version
8
Creation date
2023-11-02
Last date published
2024-04-11
Category
Administrator Guide
Solution
Cloud
Abstract

Generate an API key and make your first API call.

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, from Cortex XSOAR.

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 Cortex XSOAR API is documented in detail in the Cortex XSOAR API Reference Guide.

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

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

  1. Get your Cortex XSOAR API Key.

    1. In Cortex XSOAR, navigate to Settings & InfoSettingsIntegrationsAPI 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 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. Use the Get Started with APIs to create the advanced API authentication token to use in scripts.

    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.

      You can view the Expiration Time field for each API key at Settings & InfoSettingsIntegrationsAPI Keys . In addition, Cortex XSOAR displays an 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. 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.

    7. Click Save to generate the API Key.

    8. Copy the API key, and then click Done. This value represents your unique Authorization:{key}.

      Caution

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

  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.

  3. For Standard API Keys, 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}/xsoar/{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}/xsoar/{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}/xsoar/{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}/xsoar/{name of api}/{name of call}",
    						headers=headers,
    						json=parameters)
        return res