Ignition 8.3 API Usage Guide (via Postman)

[alexlu]

Ignition 8.3 API Usage Guide (via Postman)

Last revision - 7/30/2025

---

Ignition 8.3 OpenAPI Documentation

1. Login via - http://localhost:8088/data/app/login
2. Access OpenAPI docs - http://localhost:8088/openapi

Postman

Setup and Importing Configuration

1. Clone the 83-api GitHub resources from this repository: inductiveautomation/83-api
2. Import the Collection config file (8.3.postman_collection_v2.json) from the downloaded repository. This contains the config for all of the base routes and environments for the Resource routes which have been migrated from the IDB.
3. On the 8.3 Collection parent level in Postman, navigate to Collection variables.
4. Set the desired target gateway address as necessary (default - localhost:8088)
5. Generate an API token with write-level access on the test gateway by following the steps below and update the api_token variable in Postman Collection variables with the token key that's returned.

---

Steps to Create your first API Token with Proper Security Level Access Assigned

1. Under Platform > Security > Levels, ensure that a write-level Security Level has been created. Access and read permission levels may also be desired and configured at this time. Example of what that would look like:

2. In Platform > Security > General Settings, assign the write-level Security Level to Gateway Write Permissions and choose the "AnyOf" option (unless intent is otherwise):

3. On the API token, assign the Security Level with write access:

5. Find and update the api_token variable in Postman Collection variables with the token key.

At this point, requests sent using the API token should be properly authorized since write level access has been configured and granted.

✦✦ Ensure that API token(s) are PROTECTED at all times, as they are the keys to the kingdom that is Ignition ✦✦

---

Some Important Notes

• **Protip: Copy the generated token resource files from data/config/CORE/ignition/api-token into data/config/EXTERNAL/ignition/api-token which sits at a higher inheritance level than core as resources in core may be deleted at will during testing and development (ie. see the "Retriggering Migration" section down below).

  • A gateway restart is required after this since resource files have been affected directly on the filesystem (or alternatively run the Config Sync Request route) so that the system will pick up the new resource changes on the filesystem.
  • Any gateway config resource that is edited directly on the filesystem does not automatically picked up unless the Config Sync Request route is called which prompts the gateway to sync changes immediately.

• Be sure to hit Save in Postman after modifying any variables to apply the changes, or they will not take effect!

Config Usage

The imported 8.3 Collection contains all of the base routes for the new 8.3 API resource routes. The route types can essentially be broken down into 3 categories. With each of these, there are slight differences in the routes. Routes that only apply to specific resource types (eg. Singleton vs. Non-singleton (ie. Named Resource and Extension Point types) have been organized into their respective Resource types. Additional info can be found for a particular resource by running the Describe Type route:

Resource Route Categories

Singletons

• Examples: ignition/cobranding, sfc/chart-settings

Named Resources

• Examples: ignition/alarm-journal, database-connection, database-driver, database-translator, schedule, holiday, images
  • Note that ignition/images contains no routes because they’re expected to be managed through Image Management in the Designer.

Extension Points

• Examples: ignition/api-token, schedule

The general process for CRUD of any of these resource types using the imported Postman configs is essentially the same. The api_token Collection variable that was set during setup comes in handy as all of the requests have already been preconfigured with the X-Ignition-API-Token header which references that variable. Other subsystem-specific variables have also been added in the form of Environment configs to allow quick switching between the different contexts as will be shown in the examples below.

For each of the requests below, be sure to switch to the desired Environment (or create new if one doesn’t already exist):

Create Resource

1. Update the payload_create Environment variable with the desired config parameters.
2. Run the Create Resources route.

Read Resource

1. Named Resource or Extension Points: Run the Non-singleton/Find Resources route.
2. Singletons: Run the Singleton/Details route.

Update Resource

1. Updating and/or renaming resources will require that the correct signature for the existing resource be included. The Non-singleton/Find Resources and Singleton/Details have been preconfigured with post-run scripts that set the signature Environment variable when locating the resource. So first run either of those.

2. And then run the desired Modify Resources or Non-singleton/Rename routes to modify the existing named resources or extension points.

3. Make sure to update payload_modify and/or rename Environment variables as necessary

Delete Resource

1. Resource deletion also requires a signature match so similar to the steps for updating/renaming resources, run the Non-singleton/Find Resources or Singleton/Details routes first to grab the corresponding signature.
2. And then run the Singleton/Delete Resource or Non-singleton/Delete routes.

Development Modes

Usage of the Development Mode CRUD routes are fairly straightforward. Simply switch to the modes Environment before running and updating the variables with the desired values before running.

Gateway Config and Project Sync

Recall that the Config Sync Request route is useful for syncing any gateway config changes made directly on the filesystem without requiring a gateway restart. Project Sync Request does the same except with project file changes. Their respective Sync Info routes do just as their name implies to return info about the last known sync request.

---

8.3 Gateway Config Migration

Basic Overview of Migration Process

The migration process takes place at the beginning of each gateway startup. The gateway will look for any tables in the Internal IDB that have a migration strategy implemented and performs a migration of the configuration found in the applicable table into resource files which are stored in the data/config/core directory within their respective resource type folders. Once this migration has been completed, the IDB table name is added to the MIGRATED_TABLES_8_3 IDB table for record keeping so that the migration does not have to be performed again during the next gateway startup.

Retriggering Migration

Knowing this, it may be useful to retrigger migration for various reasons (eg. to quickly configure config settings in the old system using the existing Wicket pages and triggering migration to bypass the new WebUI ). The procedure to do this is as follows:

1. Delete the desired table(s) from the MIGRATED_TABLES_8_3 IDB table
2. Remove the corresponding resource files from data/config/core (because migration will not complete properly/entirely if duplicate resource files are found for a particular resource)
3. Restart the gateway.

Alternatively to simply retrigger migration for all resources:

1. Drop the MIGRATED_TABLES_8_3 IDB table
2. Delete data/config/core
3. Restart the gateway. **Important note that any specific resources can be saved prior to deleting core and copied back in post migration if you wish to keep them (good example - ignition/api-token).

Backup / Restore to Gateway

At the time of this writing, an 8.1 gateway backup can be restored to 8.3 for testing. However, taking a backup in 8.3 has not yet been fully implemented (this section will be updated once that effort has been completed).

API Auth Token for Routes

Additional API tokens can be generated via the ignition/api-token resource to use with the X-Ignition-API-Token header for proper authentication in requests.

Other Useful Info and Resources

• http://localhost:8088/web/status/sys.internaldb - Internal DB page

[Jared_Diamond]

Hello, I'm trying to use the API key functionality described in this thread to perform CRUD operations on my module's resources using Postman. However, I'm running into issues.

The script shared in the original post no longer works—it now returns a 422 Unprocessable Entity error:

@alexlu

var csrf;
var token;
var key_name = 'mytoken';

await fetch('/data/app/session', {
    method: 'get',
    headers: {'Accept': 'application/json', 'Content-Type': 'application/json'},
}).then(response => response.json()).then(data => {csrf = data['csrfToken'];});

await fetch('/data/api/v1/api-token/generate', {
    method: 'post',
    headers: {'Content-Type': 'application/json', 'X-CSRF-Token': csrf}
}).then(response => response.json()).then(data => {token = data});

await fetch('/data/api/v1/resources/ignition/api-token', {
    method: 'post',
    headers: {'Content-Type': 'application/json', 'X-CSRF-Token': csrf},
    body: JSON.stringify([{name: key_name, config: {profile: {type: 'basic-token', secureChannelRequired: false, timestamp: Date.now(), securityLevels: ['Authenticated/Roles/Administrator']}, settings: {tokenHash: token.hash}}}])
}).then(response => {if (response.ok) {
	console.log({token: key_name.concat(":").concat(token.key)});
} else {
	console.log(response.json);
}});

I can still create API keys through the 8.3 UI, but those keys don’t seem to work either—any request I make with them gets a 403 Forbidden response, even when I uncheck the 'Require secure connections for API Keys' option. The UI only lets me configure the name and description, so I'm wondering if something else needs to be set up in my module's gateway hook, like explicitly adding permissions?

Is there something I need to do on the backend to allow these keys to access my module's resources?

[alexlu]

Hi Jared,

The repo needs to be and is in the process of being updated but what it comes down is the permissions assignment of the token. To fix this you can create a token thru the UI with a write-level Security Level assigned. I've included steps for doing so below.

1. Under Platform > Security > Levels, ensure that a write-level Security Level has been created. Access and read permission levels may also be desired and configured at this time. Example of what that would look like:

2. In Platform > Security > General Settings, assign the write-level Security Level to Gateway Write Permissions and choose the "AnyOf" option (unless intent is otherwise):

3. On the API token, assign the Security Level with write access:

At this point, requests sent using the API token should be properly authorized since write level access has been configured and granted. Please feel free to reach out again if you encounter issues or have any questions.

Thanks,

Alex

[Jared_Diamond]

That did the trick. Thank you for the detailed response!