Accessing the iGrafx Platform REST API

The public REST API for the iGrafx Platform allows you to interact with the application in an automated fashion. It was introduced with the iGrafx Platform version 16.2 and coverage has been and will continue to be improved over time on request.

The REST API can use either basic authentication or an API key to authenticate users.

Basic Authentication

If using basic authentication be aware that login names and passwords are sent across the network unencrypted. Malicious users can intercept this information. You can use Basic authentication and still protect account information by enabling SSL (HTTPS) encryption for this iGrafx Platform.

API Key Authentication

An API key for your user gives the person with the key all permissions to the Process Design application as if they were you. Do not give your API key to other people or save it in files you send to other people. It cannot be deconstructed into your password, but should be treated as a password itself.

A warning will also appear on the REST API page if your server uses unencrypted HTTP.

Enabling the API

By default the API is disabled. To enable it, follow these steps:

1. Open the iGrafx Platform using an admin account.
2. Go to Administration > Support > REST API
3. The API is disabled by default, enable it if you plan to test or use it.
4. Determine whether you will use basic authentication, API keys, or both and enable appropriately.

Accessing API documentation

Minimum permissions for a user to access the REST API documentation is a Server Role including Access Support Features.

The extent of the REST API depends on the exact version of the iGrafx Platform application server, and the documentation for the REST API is contained within the application.

A link to the API documentation can be found on the REST API page as shown below. You can bookmark this link to make it easier to access.

Accessing the API

The REST API validates the permissions and licenses of the user accessing the API end point. It is recommended to create a dedicated API user with permissions and licenses limited to your use case.

To successfully access an API endpoint:

1. The API must be enabled as shown above
2. The user that the supplied credentials identifies must have the server permission to access the API
3. The user must be licensed for the activity that the endpoint uses
4. The user must have repository and/or server permission to do the operation the endpoint supports

Getting your API Key

As an administrator account (With the API enabled):

1. Administrator → User Management
2. Find the user who needs an API Key
3. Click either their name or the edit button.
4. Scroll down and select Generate API Key.

Ways to use the API key

API Key Change

Starting with 17.7.4, iGrafx no longer supports API Keys in the query parameter. Please use X-AUTH-APIKEY in the header for continued use of the API Key.

Using an API Key in the request header

After getting your API Key you would need to set the value of "X-AUTH-APIKEY:" to the the API Key value you got from the Getting your API Key. 

CURL -H 'X-AUTH-APIKEY: YOUR_KEY_HERE' 'https://igrafx.com/api/info/version'

A request header is used so that the user's browser sends information to a web server containing the details of what the user's browser wants / will accept back the server. We can add our request header here containing the API Key. 

Related articles