API keys, secrets, and tokens

Cortex provides three credential types to help you manage authentication and access securely. API keys grant programmatic access to Cortex data and integrations, secrets store sensitive credentials for use across your configurations, and personal access tokens allow individual users to interact with the Cortex API under their own permissions. Using the right credential type for each use case helps minimize risk and maintain the principle of least privilege.

Managing API keys

API keys enable programmatic access to your Cortex data, from high-level Scorecard stats to detailed information about specific entities in your catalogs. You can manage API keys through the Cortex UI or via the API. Both require the Edit API keys permission.

For a full reference of available API key endpoints, see API Keys.

Creating an API key in Cortex

Follow the steps below to create an API key in Cortex. Note that you must have the Edit API keys permission to create or delete API keys, or to edit their name or description.

Assign only the permissions necessary for the API key's intended purpose. API keys support the same default permissions and custom roles available to individual users.

API keys with an expiration date trigger notifications before they expire. You'll receive a reminder seven (7) days before the expiration date, followed by a second reminder the day before, giving you time to rotate or renew the key before it becomes invalid.

There is no limit to the number of API keys you can create!

1. From the main sidebar, click your avatar in the bottom-left corner.

2. Click Settings.

3. From the Settings menu, scroll to the Security and access section, then select API keys.

4. Click Create new key in the upper-right corner.

5. Do the following:

   1. Below Name, enter a name for the key (required).

   2. Below Description, enter a brief overview of the key.

   As a best practice, include details about what the API key is used for. This helps ensure that other users do not accidentally delete an important API key.

   1. From the Role drop-down menu, select the permissions level for the key (required).

   2. Below Expiration date, set an expiration date for the key. The key automatically expires at the end of the chosen day based on the current time zone.

6. Click Create API key. The key is created and displayed. Copy the key and store it in a secure location, as it will not be displayed again after you refresh or navigate away from the page.

   The key is only displayed once! Copy it and store it in a secure location before navigating away from this page. Cortex only retains the last 4 digits of the key for reference; the remainder is encrypted and cannot be recovered.

Modifying an API key

You can update the name and description of an API key after it has been created.

The key value itself cannot be modified. To change it, delete the existing key and create a new one. Learn more about best practices for API key rotation below.

1. From the main sidebar, click your avatar in the bottom-left corner.

2. Click Settings.

3. From the Settings menu, scroll to the Security and access section, then select API keys.

4. Locate the API key you want to edit, then click the pencil icon next to that key.

5. Do any or all of the following:

   • Below Name, enter a new name.

   • Below Description, enter a new or updated overview of the key.

   • Below Expiration date, enter a new or updated expiration date.

6. Click Save. The key is updated.

Requiring an expiration date for API keys

Cortex requires all new API keys to have an expiration date. For existing keys, an expiration date is optional.

API key expiration is enforced globally. Once enabled, all newly created API keys in your Cortex workspace are subject to the specified maximum lifetime.

1. From the main sidebar, click your avatar in the bottom-left corner.

2. Click Settings.

3. From the Settings menu, scroll to the Security and access section, then select Security policy.

4. Toggle on Require API token expiration.

5. Below Maximum lifetime for new tokens, enter the number of days after which new tokens will expire.

   Maximum lifetime cannot exceed 400 days.

6. Click Save. API keys created going forward will expire after the maximum lifetime you specified in step 5.