API Keys

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

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

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:

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

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

   

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

   

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.

   

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

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

   

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.

   

   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

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