API keys, secrets, and tokens

In Cortex, use API keys, secrets, and personal access tokens to maintain security and access across different features.

Managing API keys in Cortex

You can use API keys to enable programmatic access to all of your data within Cortex, including everything from high-level Scorecard stats to detailed information about specific entities in your catalogs.

For more information on the Cortex API, see the documentation here.

Managing API keys via the Cortex API

It is possible to create, read, update, and delete API keys via the Cortex API. Your API token must have the Edit API keys permission.

See the API documentation for more information.

Managing API keys in the Cortex UI

You must have the Edit API keys permission to create or delete API keys or to edit their name or description.

We recommend using the fewest possible permissions based on the purpose of the API key. An API key can have one of the default permissions or can be assigned a custom role. These permissions mirror individual permissions and roles.

Create API key in the Cortex UI

To create a new API key:

1. Navigate to the API key settings page

2. At the top of the page, click Create API key.

3. Configure the API key:

   • Roles: Select a role for the API key.

   • Name: Enter a name for the API key.

   • Description: Enter a description for the API key.

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

   • Expiration date: Set an expiration date for the API key. The key will expire at the end of the chosen day based on the current time zone.

4. At the bottom of the modal, click Create API key.

Copy and store the API key

Once you click Create API Key, the full key will be displayed at the top of the page. Copy the key and store it in a secure location, as the key will not be displayed again after you refresh or navigate away from the page.

Cortex will only preserve the last 4 digits of the key for cross-referencing, but the rest of the key will be encrypted.

Modifying an API key

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

You cannot make changes to the key value itself. If you need to change the key value, you will need to delete it, confirm the deletion, then create a new key. Learn more about best practices for API key rotation below. There is no limit to the number of API keys you can create.

To edit an API key's name or description:

1. Navigate to the API key settings page.

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

3. In the modal, make changes to the name and/or description.

4. Click Update API key.

Best practices for API key rotation

When an API key for an integration in Cortex expires, the best practice is to delete the expired key and create a new one. Cortex does not currently support in-place rotation or regeneration of API keys for integrations.

We recommend the following steps to minimize disruption of existing integrations:

1. Create a new API Key in the third-party tool you're integrating:

   • Generate a new key with the required permissions and details.

2. Remove the old integration configuration in Cortex:

   • Make a note of the alias name then delete the old configuration in Cortex. You will need the alias name in the next step.

     • As an example, assume the old integration's alias is cortex-github.

3. Create a new integration in Cortex with the new API key and the same alias as the previous configuration:

   1. Create a new integration configuration and use the same alias as the previous configuration.

      • Following the example mentioned in the previous step, you would add cortex-github as the alias for this new configuration.

   2. If you had multiple configurations for this integration, and the integration with the expired key was set as the default, then set this new configuration as the default.

      • This helps avoid disruptions to dependent workflows or entities, as entities will fall back to the default configuration if their YAML file references an alias that doesn't exist.

4. Monitor:

   • After updating, monitor the integration for any issues.