Generate an API Key

Before using the Expander API, generate an API Key and collect the API Key ID and FQDN.

Before you can begin using Cortex Xpanse Expander API, you must generate an API Key and collect the API Key ID and FQDN from Expander.

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

Expander 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. Generate a new Expander API Key.

   1. In Expander, navigate to Settings → Configurations → Integrations → API Keys.
   2. Select + New Key.
   3. Select the User Roles tab, and 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 provided script to create the advanced API authentication token.

      Note

      To integrate with Cortex XSOAR, you must generate a Standard Key.
   4. If you want to define a time limit on the API key authentication, check Enable Expiration Date and select the expiration date and time.

      Navigate to Settings → Configurations → Integrations → API Keys to view the Expiration Time field for each API key. In addition, Expander displays a API Key Expiration notification in the Notification Center one week and one day prior to the defined expiration date.
   5. Select a Role to specify the desired level of access for this key.

      You can view the permissions for each role by expanding the Components on the lower part of the page. The list of available roles will match the roles defined on the Settings → Configurations → Access Management → Roles page.
   6. Optionally, enter a Comment that describes the purpose of the API key.
   7. Click Save to generate the API key.
   8. Copy the Generated Key, and then click Close.

      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 Generated Key notification.
2. Get your Expander 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 you 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}/
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