---
title: "API Keys"
---

# API Keys

> An API Key is a unique identifier used to authenticate and authorize access to a system's resources without requiring a username and password for each request. In Ignition, API Keys are used to securely authenticate API requests made to the Gateway. They allow external applications, scripts, and services to interact with Ignition without needing interactive user authentication.

## Using API Keys

When an API Key is created, the Gateway hashes the key and stores it securely. The key itself is only visible to the user at the time of creation. API Keys are then used to authenticate HTTP requests by including them in the request header. The system verifies the provided key, checks associated security levels, and grants access accordingly.

:::caution
API Keys grant full access to the Gateway’s HTTP API routes, including the ability to modify configuration, tags, and projects. Improper use of API Keys may result in data loss, security breaches, or performance issues. Only issue keys to trusted users or systems, and ensure appropriate security levels are applied. To track configuration changes made through API requests, [enable auditing](platform/audit-log-and-profiles/audit-log-and-profiles.md). Mutative API calls (such as POST, PUT, and DELETE) are recorded in audit logs with the user, IP address, and API key. **GET requests are not recorded in audit logs.**
:::

API Keys are required to access newly introduced resource-based configuration routes, including endpoints under `/data/api/v1/resources`, `/data/api/v1/sync`, and `/data/api/v1/modes`. These routes are documented in the Gateway’s [API Documentation](platform/gateway/openapi/openapi.md).

### Example: Using an API Key in an HTTP Request

To authenticate API requests, include the API Key in the `X-Ignition-API-Token` header using the following format:

```http
X-Ignition-API-Token: <your-api-token>
```

```http title="Example"
GET /api/resource HTTP/1.1
Host: your.gateway.address
X-Ignition-API-Token: <your-api-token>
```

This method is required for all routes documented in the Gateway's [API Documentation](platform\gateway\openapi\openapi.md) interface (`/openapi`).

## Creating an API Key

To create an API Key, follow the steps below.

:::note
Users must have proper write permissions defined on the Gateway's [Security > General Settings](platform/security/gateway-general-security-settings/gateway-general-security-settings.md#roles-and-permissions) page to create API Keys.
:::

1. Access your Gateway and navigate to **Platform** > **Security** > **API Keys**.

2. Select **Create API Key +**. The Create API Key form will appear.

   ![](imgs/create-api-key.png)

3. Currently, **Basic Token** is the only type available. Click **Next**.

   ![](imgs/create-type-selection.png)

4. Enter a name for your API Key, and optional description. By default, **Require secure connections for API Keys** is enabled.

   In this example, the API Key is named **Test_Key**.

   ![](imgs/general-only.png)

5. Select security levels for the key. By default, the **Authenticated** level is selected and cannot be changed. If you need to add more options, they can be created on the Security > [Levels](platform/security/identity-provider-authentication-strategy/security-levels/security-levels.md) page.

   In this example, a new security level named **apiKeys** was created and selected.

   ![](imgs/security-level-only.png)

6. Click **Create API Key**.

7. A warning message will appear with your API Key shown. Copy the key and store it securely, then select **I have stored my API Key for future reference.**

   ![](imgs/create-copy-securely.png)

   :::caution important
   This is the **only** opportunity to copy the key and store it securely (i.e., with a reputable password manager or secure vault solution), as it **cannot** be retrieved again.
   :::

8. Click **Done**.

## Managing API Keys

The API Keys page lists all created keys in a table with the following columns:

* **Name**: The key's name.
* **Description**: An optional description provided at creation.
* **Created**: The date and time the key was created.
* **Enabled**: Indicates whether the key is currently active or disabled.

### Editing, Renaming, Duplicating, or Deleting

Open the three dots menu next to a key to choose an action:

|Menu | Action Descriptions|
|--|--|
|![](imgs/menu-items.png) | **Edit**: Modify the key's settings. **Rename**: Change the key's display name. **Duplicate**: Copy the key's settings to create a new key. **Disable**: Temporarily revoke access without deleting the key. **Create Override/Move Definition**: Manage resource definitions for deployment modes. For details on overriding named resources, see the [Resource Definitions](platform/gateway/web-interface/platform/gateway-deployment-modes/gateway-deployment-modes.md#resource-definitions) section on the Gateway Deployment Modes page.  **Delete**: Permanently remove the key. Deleting an API Key **immediately revokes access** for any services or applications using it. This action **cannot be undone**. |

When duplicating, the Duplicate API Key form copies all current settings. Enter a new unique name and click **Duplicate API Key**.

![](imgs/duplicate-api-form.png)