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.

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 Authorization header using the following format:

Authorization: Bearer <tokenName>:<key>

Example

GET /api/resource HTTP/1.1
Host: your.gateway.address
Authorization: Bearer <tokenName>:<key>

This method is required for all routes documented in the Gateway's API Documentation interface (/openapi).

Legacy Usage

Some older or undocumented routes may still require the legacy X-Ignition-API-Token header format. These routes are not included in the OpenAPI specification and may not support the standard Authorization header.

Creating an API Key

To create an API Key, follow the steps below.

note

Users must have write permissions as defined by the security level(s) in the Gateway's security settings 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. Select the applicable security levels to proceed.

   In this example, the API Key is name Test_Key, and all security levels are enabled.

   

5. Click Create API Key.

6. 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., a reputable password manager or secure vault solution), as it cannot be retrieved again.

7. Click Done.

Managing API Keys

All created API Keys are listed on the API Keys page. In addition to being able to create API Keys from this page, it also provides an overview of existing API Keys, including their name, description, and creation date.

Editing or Deleting API Keys

To modify or remove an API Key, click the three dots menu next to the key and select the appropriate action.

caution

Deleting an API Key immediately revokes access for any services or applications using it. This action cannot be undone.

Choosing Duplicate as New Key retains all applied settings under a new name.