Skip to main content

Access the REST API

Turn on the REST API, choose how callers authenticate, generate an API key for the user the integration runs as, and make your first authenticated request.

Prerequisites​

  • Requires a platform administrator: enabling the API and generating API keys are admin-only.
  • The caller (the user whose credentials the integration uses) needs the Access REST API server permission, and a license for whatever each endpoint does. Create a dedicated API user whose permissions and licenses match only what the integration needs.
  • To open the embedded API documentation, a user needs the Access Support Features server permission.

Steps​

  1. Open the platform as an administrator and go to Admin → Support → REST API.

    The REST API page under Admin, Support, with the API documentation link and the Allow access via API Key toggle

  2. Turn on Allow access via API Key. On-premises, turn on Enable API first.

  3. Generate an API key for the integration's user:

    1. Go to Admin → User Management and open the user (Edit).
    2. Under API Keys, click Generate API Key, then copy the key. Treat it like a password — it grants everything that user can do, and you can't retrieve it again after you leave the page.

    The API Keys section of a user's edit page, with the Generate API Key button

  4. Send the key in the X-AUTH-APIKEY header on each request:

    curl -H "X-AUTH-APIKEY: YOUR_KEY_HERE" https://your-igrafx-host/api/info/version

Verify​

A call to GET /api/info/version returns the platform version, which confirms the API is on, your authentication works, and that user can reach it.

Troubleshooting​

If a call fails, check the response status:

  • 401 or 403 — authentication failed. Confirm the API key is valid and not revoked, and that it's sent in the X-AUTH-APIKEY header, spelled exactly.
  • 400 — the request was rejected. Check the request body for valid JSON (mind the quote escaping) and, where the call takes a query, valid iGrafx Query Language (IQL).

A successful call returns 200 with a JSON body.

Live Testing returns 401​

The Live Testing feature in the embedded API documentation authenticates with basic authentication: your username and the password stored for your account in the iGrafx Platform database. If you sign in through single sign-on (SSOSSO An authentication scheme that lets users sign in once with an identity provider and access Process360 Live without re-entering credentials.) — or your account came from Active Directory/LDAP or SCIM — your password lives with your identity provider, so there's no platform password for basic authentication to use and the call returns 401. An API key doesn't help: it works from a REST client, but Live Testing can't use it.

  • Local account: ask an administrator to set a platform password for your user under Admin → User Management, then use that password in Live Testing.
  • SSOSSO An authentication scheme that lets users sign in once with an identity provider and access Process360 Live without re-entering credentials., Active Directory/LDAP, or SCIM account: test from a REST client such as Postman instead, using the API key in the X-AUTH-APIKEY header as above.