# 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](/configure/settings/api-keys/secrets.md) store sensitive credentials for use across your configurations, and [personal access tokens](/configure/settings/api-keys/personal-tokens.md) 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](/api/readme/api-keys.md).

## Creating an API key in Cortex <a href="#create-api-key" id="create-api-key"></a>

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.

{% hint style="info" %}
Assign only the permissions necessary for the API key's intended purpose. API keys support the same [default permissions](/configure/settings/managing-users/permissioning.md) and [custom roles](/configure/settings/managing-users/permissioning/custom-roles.md) available to individual users.
{% endhint %}

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.

   <div data-gb-custom-block data-tag="hint" data-style="info" class="hint hint-info"><p>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.</p></div>

   3. From the *Role* drop-down menu, select the permissions level for the key (required).
   4. 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.

   <div data-gb-custom-block data-tag="hint" data-style="info" class="hint hint-info"><p>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.</p></div>

## Modifying an API key

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

{% hint style="info" %}
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](#best-practices-for-api-key-rotation).
{% endhint %}

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.

{% hint style="info" %}
API key expiration is enforced globally. Once enabled, all newly created API keys in your Cortex workspace are subject to the specified maximum lifetime.
{% endhint %}

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.

   <div data-gb-custom-block data-tag="hint" data-style="info" class="hint hint-info"><p>Maximum lifetime cannot exceed 400 days.</p></div>
6. Click **Save**. API keys created going forward will expire after the maximum lifetime you specified in step 5.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.cortex.io/configure/settings/api-keys.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.