How-toInfor OS (ION API)ION API / Authorized Apps

How to Create an .ionapi File and Service Account in Infor OS

Question
how to create .ionapi file Infor OS service account ION API

Also searched as

  • Infor ION API backend service authorized app
  • download ionapi credentials Infor OS
  • Infor ION API service account access key secret key
  • ION API client id client secret saak sask

Short answer

An .ionapi file is a JSON credentials file you download from ION API after registering an Authorized App of type Backend Service and creating a service account for it. It carries the tenant, client id, client secret, the token and authorization endpoints, and the service account keys that your scripts or integrations use to request an OAuth 2.0 access token.

Applies to: Infor OS multi-tenant cloud (CloudSuite) and Infor OS on-premises with ION API; menu names vary slightly by release

Create the credentials

  1. 1Sign in to Infor OS Portal with a user who holds the IONAPI-Administrator security role, then open the ION API application from the apps menu.
  2. 2Choose Authorized Apps and select the add (+) button to register a new application.
  3. 3Set the Name (for example ERP_Reporting_Svc), pick the type Backend Service, and give it a clear description so the next administrator knows its purpose.
  4. 4Save. ION API shows the Client ID and Client Secret for the app and lets you download the .ionapi file for the application itself. Keep this separate from the service account keys.
  5. 5Open User Management in Infor OS, create a user of type Service Account, and assign only the security roles the integration needs (for example the roles for the IDO, M3 API or IDM access it will call).
  6. 6On the service account, use the option to create access keys. The dialog returns a Service Account Access Key and a Service Account Secret Key. The secret key is shown only once, so copy it now.
  7. 7Back in ION API, download the .ionapi file and confirm it contains the service account key fields, or add them if your script keeps them separately.
  8. 8Store the file in a secrets vault, never in source control, and test by requesting a token from the pu/ token endpoint named in the file.

What is inside an .ionapi file

The file is plain JSON. The fields you will use most are ti (the tenant id), cn (the client name), ci (client id), cs (client secret), iu (the base ION API URL for the tenant), pu (the base URL for the authorization server), oa (authorization endpoint path), ot (token endpoint path), or (revoke path), saak (service account access key) and sask (service account secret key). A trailing version field and the ev field for the environment are also present.

Because the client secret and the service account secret are both in the same file, treat it like a password. Anyone who holds it can call every API the service account is entitled to, from any machine, until you revoke the keys. Rotate by deleting the access key on the service account and creating a new one, then update the file where it is stored.

{
  "ti": "ACME_PRD",
  "cn": "ERP_Reporting_Svc",
  "dt": "12",
  "ci": "ACME_PRD~xxxxxxxx",
  "cs": "<client secret>",
  "iu": "https://mingle-ionapi.inforcloudsuite.com",
  "pu": "https://mingle-sso.inforcloudsuite.com:443/ACME_PRD/as/",
  "oa": "authorization.oauth2",
  "ot": "token.oauth2",
  "or": "revoke_token.oauth2",
  "ev": "U1234567",
  "v": "1.0",
  "saak": "<service account access key>",
  "sask": "<service account secret key>"
}

Requesting a token with the password grant

Backend services use the OAuth 2.0 password grant, where the service account access key is the username and the secret key is the password. You POST to pu plus ot with grant_type=password and send the client id and client secret using HTTP Basic authentication or in the form body.

The response contains access_token, token_type Bearer and expires_in. Call the API gateway at iu followed by the tenant id and product path, for example iu/TENANT/M3/m3api-rest/v2/execute/MMS200MI/GetItmBasic, with the header Authorization: Bearer plus the token. Refresh by requesting a new token before expiry rather than caching a token for days, because expired tokens return 401.

curl -s -X POST "https://mingle-sso.inforcloudsuite.com:443/ACME_PRD/as/token.oauth2" \
  -u "ACME_PRD~xxxxxxxx:CLIENT_SECRET" \
  -d "grant_type=password" \
  -d "username=SERVICE_ACCESS_KEY" \
  -d "password=SERVICE_SECRET_KEY"

Choosing the right Authorized App type

Backend Service is for server to server jobs with no human present: nightly extracts, middleware, and AI agents. Web Application and Mobile or Desktop types are for interactive sign in, where a user consents and the app receives an authorization code. Pick the type that matches how the caller authenticates, because you cannot switch a registered app between flows without re-registering it.

Scope the service account tightly. The account inherits whatever its security roles allow in each downstream product, so a reporting integration should not hold the same roles as an administrator. If you need separate audit trails per integration, create one Authorized App and one service account per integration instead of sharing one file.

Common pitfalls

  • !Losing the Service Account Secret Key: it is displayed once. If you did not save it, create a new access key.
  • !Using the client secret as the password. The password grant uses the service account secret key (sask) as the password and the access key (saak) as the username.
  • !Committing the .ionapi file to Git or pasting it into a chat or ticket. Treat it like a production password and rotate it if it leaves the vault.
  • !Giving the service account administrator roles because it is faster. Calls then succeed everywhere, which hides missing role design and widens the blast radius.
  • !Hard coding the token endpoint from another tenant. The pu value is tenant specific, so always read it from the file.

How an ERP-grounded AI assistant handles this

When an AI assistant calls Infor through ION API, it should use a dedicated service account with read-only roles and a short lived token, and the credentials should live in the vault the model runtime reads, never in a prompt. ERPray connects through this kind of service account, shows the query it ran, and respects the ERP roles attached to the account, so an assistant can only see what the account is entitled to see.

See ERPray

Frequently asked questions

Where do I download the .ionapi file in Infor OS?

Open ION API from the Infor OS apps menu, go to Authorized Apps, select your registered Backend Service app and use the download option for the credentials file. You need the IONAPI-Administrator role to see the Authorized Apps screen.

Can I reuse one .ionapi file for several integrations?

You can, but it is poor practice. Every call is then attributed to the same account, you cannot revoke one integration without breaking the rest, and the role set grows to the union of all needs. Create one app and service account per integration.

How long does an ION API access token last?

The expires_in value in the token response tells you. It is typically in the range of minutes to a couple of hours depending on tenant configuration. Request a new token before it lapses instead of assuming a fixed lifetime.

Do I need a service account for the OAuth password grant?

Yes for Backend Service apps. The service account supplies the access and secret keys that act as username and password, and its security roles decide what the token may do in M3, SyteLine, LN, IDM or other products.

Related

Error fix

Fix a 401 Unauthorized error from Infor ION API

A 401 from ION API almost always means the credentials in the .ionapi file no longer match what ION API Gateway expects - not that the password is simply wrong. Check whether the Authorized App or service account behind the file was revoked, regenerated, expired, or issued for a different tenant, then re-test with a direct OAuth2 client_credentials call before touching any calling code.

Advanced

How to Call M3 API (MI Programs) Through ION API

Calling M3 from an external system today almost always means going through ION API rather than the older direct MvxAPI SOAP endpoint: you create an ION API authorized app or service account in the ION API portal, download its .ionapi credential file, obtain an OAuth 2.0 access token, and call the M3 MI program transaction through the m3api-rest execute endpoint with that token.

How-to

How to query Infor Data Lake with Compass SQL

Compass is the SQL query layer in Infor OS for querying Infor Data Lake, where flattened copies of BODs published over ION are stored by Noun and Verb. Open a Compass SQL Workbench tab, browse the schema for the correct table, and run a filtered SELECT rather than pulling the full history, since Data Lake tables can hold years of append-only data.

How-to

How to Search and Upload Documents with the Infor IDM REST API

Infor Document Management (IDM) exposes REST services through ION API under the IDM path of your tenant. You search items with a $query expression written against an entity and its attributes, read the returned resource links to fetch the file, and create new items with a multipart request that carries an XML description of the entity and attributes plus the file stream.

Error fix

Diagnose and fix a failed BOD document flow in ION Desk

A Document Flow showing Failed in ION Desk means a BOD (Business Object Document) stopped either at schema validation, at the mapping step, or at the target application. Open the failed instance's detail to see the exact failing element, fix the source data or mapping, then use Resubmit rather than re-triggering the original transaction to avoid duplicates.

Error fix

Fix a Ming.le homepage widget that will not load

A blank or endlessly spinning Ming.le widget is usually a permissions, session, or backend availability problem, not a broken widget itself. Confirm the issue is widget-specific, check the user's Security Group access to the underlying app, and look at the widget's network calls in browser dev tools to see whether it is failing with 401/403 or simply timing out against a down service.

AI for ERP

AI Agents Over Infor ION API, BODs, and the Infor Data Lake

Build AI agents on Infor ION API Gateway, BODs, and Data Lake, alongside or instead of Infor's own GenAI features, with your choice of model and hosting.

AI for ERP

AI for Infor M3: A Practical Path from MI Programs to a Private Assistant

Add grounded AI to Infor M3: natural-language answers over MI programs and MEC, agents for distribution and manufacturing, on-prem or private cloud in Europe.

Stuck on Infor OS (ION API)?

Talk to engineers who work inside Infor OS (ION API) every week, and who build private AI that answers these questions from your own ERP data.

Talk to an ERP engineerBrowse ERP Help
All ERP Help articles