Infor OS / ION API Gateway REST Capabilities, Rate Limits & Pagination

TL;DR

• Bottom line: The ION API Gateway is a NodeJS reverse proxy that fronts all Infor CloudSuite applications with OAuth 2.0, throttling policies, and protocol transformation (SOAP-to-REST) — every Landmark screen field is accessible via REST through the gateway.
• Key limit: Default 1-minute timeout (max 5 min); buffered policies capped at 10 MB payload; Compass V2 pagination at 100K rows or 10 MB per page.
• Watch out for: Throttling is per-endpoint configurable (spikeArrest + rateSmoothing), not a single global number — you must check each API suite's policy configuration.
• Best for: Real-time REST integration with Infor M3, LN, CloudSuite Distribution, and all Landmark-based applications via a unified OAuth 2.0 gateway.
• Authentication: OAuth 2.0 with four grant types — Resource Owner (server-to-server recommended), Authorization Code (web/mobile), SAML Bearer (Ming.le SSO), Implicit (SPAs). Access tokens valid 2 hours, refreshable.

System Profile

The Infor OS ION API Gateway is the centralized API management layer for all Infor cloud products. It acts as a NodeJS-based reverse proxy that receives HTTP requests from external clients, enforces security and throttling policies, and forwards them to target Infor applications (M3, LN, CloudSuite Distribution/Industrial/etc.). Every Landmark web service is accessible through the gateway, meaning every field of every screen of every Infor Landmark-based application can be read or written via REST.

This card covers the cloud-hosted ION API Gateway (Infor OS 2024.x/2025.x). On-premise ION Grid REST API v2 has a different endpoint structure and authentication model. The gateway also supports SOAP-to-REST transformation via Handlebars-based endpoint policies.

API Surfaces & Capabilities

Rate Limits & Quotas

Per-Request Limits

Rolling / Daily Limits

Throttling Policy Configuration

Infor does not publish a single global rate limit. Instead, throttling is configured per API suite endpoint via three policy types:

• Quota: Hard cap — allow requests per interval timeUnit. Can be per-user or per-endpoint.
• Throttling (rateSmoothing): After delayAfterCount requests, each subsequent request is delayed.
• Throttling (spikeArrest): Hard cutoff — maxRequestsPerPeriod sets absolute maximum.

{
  "timePeriodInMilliseconds": 60000,
  "rateSmoothing": {
    "delayAfterCount": 1000,
    "delayFactorInMilliseconds": 1000
  },
  "spikeArrest": {
    "maxRequestsPerPeriod": 1000
  }
}

Authentication

Authentication Gotchas

• Service accounts require four credentials, not two: ClientID + ClientSecret (application-level) AND AccessKey + SecretKey (service account-level). [src4]
• Token endpoint is tenant-specific: The OAuth token URL is unique per Infor cloud tenant — always extract from the .ionapi credentials file. [src3]
• SAML Bearer only works inside Ming.le: If your application runs outside the Infor OS portal, SAML Bearer grant will fail. [src3]
• Access token expiry is admin-configurable: While the default is 2 hours, tenant admins can change it. Never hardcode the expiry. [src4]

Constraints

• No single published global rate limit: Infor uses configurable per-endpoint throttling policies. You must discover limits for each API suite through testing or admin review.
• Gateway timeout is 1 minute by default: Any REST call taking longer times out. Use async patterns or request a timeout extension (max 5 min).
• 10 MB buffered policy limit: Endpoints with transformation policies cap payloads at 10 MB. This breaks large data exports.
• Compass results are ephemeral: Query results expire ~20 hours after completion. No permanent result storage.
• API documentation format required for registration: Custom API suites must use Swagger 2.0 or OpenAPI 3.0.x specs.
• On-premise vs cloud differences: On-premise ION Grid REST API v2 has different base URL and may use basic auth or client certificates.

Integration Pattern Decision Tree

START — User needs to integrate with Infor CloudSuite via ION API Gateway
|-- What's the integration pattern?
|   |-- Real-time (individual records, <1s)
|   |   |-- Infor Landmark-based app? (M3, LN, CloudSuite)
|   |   |   |-- YES --> ION API Gateway: Landmark web services via REST proxy
|   |   |   +-- NO --> Register custom API suite (Swagger/OpenAPI)
|   |   +-- Need screen-level field access?
|   |       |-- YES --> Landmark web services (every field accessible)
|   |       +-- NO --> M3 API REST v2 (m3api-rest/v2/execute)
|   |-- Batch/Bulk (scheduled, high volume)
|   |   |-- Data volume < 100,000 records?
|   |   |   |-- YES --> Compass V2 API (single query, paginate)
|   |   |   +-- NO --> Compass V2 with query chunking
|   |   +-- Need write operations (inbound)?
|   |       |-- YES --> ION Connect BOD messaging
|   |       +-- NO --> Compass V2 for read-only bulk export
|   |-- Event-driven (real-time notifications)
|   |   |-- Infor-to-Infor?
|   |   |   |-- YES --> ION Connect publish-subscribe (BOD-based)
|   |   |   +-- NO --> ION Connect + ION API connection point
|   |   +-- Need guaranteed delivery?
|   |       |-- YES --> ION Connect with acknowledgment workflow
|   |       +-- NO --> ION API Gateway webhook
|   +-- File-based (CSV/XML)
|       +-- ION Mapper + ION Connect document flows
|-- Which direction?
|   |-- Inbound --> check per-endpoint write throttling
|   |-- Outbound --> check Compass quotas (10K/min result calls)
|   +-- Bidirectional --> design conflict resolution with BOD acknowledgment
+-- Error tolerance?
    |-- Zero-loss --> ION Connect with dead letter queue + BOD replay
    +-- Best-effort --> REST API with retry + exponential backoff

Quick Reference

Step-by-Step Integration Guide

1. Download the .ionapi credentials file

The .ionapi file contains all OAuth endpoints and credentials for your tenant. Download from Infor OS Portal > ION API > Authorized Apps. [src3]

{
  "ti": "TENANT_ID",
  "cn": "CLIENT_NAME",
  "ci": "CLIENT_ID",
  "cs": "CLIENT_SECRET",
  "iu": "https://inforos-{region}.inforcloudsuite.com",
  "pu": "https://inforos-{region}.inforcloudsuite.com/{tenant}/as/token.oauth2",
  "oa": "https://inforos-{region}.inforcloudsuite.com/{tenant}/as/authorization.oauth2",
  "or": "https://inforos-{region}.inforcloudsuite.com/{tenant}/as/revoke_token.oauth2"
}

Verify: Confirm the file contains non-empty ci, cs, pu, and service account fields.

2. Authenticate and obtain an access token

Use the Resource Owner grant for backend integrations. [src3, src4]

curl -X POST "{pu}" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=password" \
  -d "username={saession}" \
  -d "password={sapassword}" \
  -d "client_id={ci}" \
  -d "client_secret={cs}"

Verify: Response includes access_token and refresh_token with token_type: Bearer.

3. Call an ION API endpoint

With the bearer token, call any registered API suite endpoint. [src3]

curl -X GET "https://inforos-{region}.inforcloudsuite.com/{tenant}/ifsservice/usermgt/v2/users/me" \
  -H "Authorization: Bearer {access_token}" \
  -H "Accept: application/json"

Verify: HTTP 200 response with JSON payload containing user details.

4. Handle pagination for Compass V2 queries

Submit a query, poll for completion, then paginate results. [src6]

# Submit query
curl -X POST ".../v2/compass/jobs" -H "Content-Type: text/plain" -d "SELECT * FROM table LIMIT 50000"

# Poll status (repeat until FINISHED)
curl -X GET ".../v2/compass/jobs/{queryId}" -H "Authorization: Bearer {token}"

# Retrieve results with pagination
curl -X GET ".../v2/compass/jobs/{queryId}/result?resultFormat=application/x-ndjson&offset=0&limit=10000"

Verify: Result set returns with expected row count; increment offset by limit for next page.

5. Implement token refresh

Access tokens expire after 2 hours. Refresh before expiry. [src4]

curl -X POST "{pu}" \
  -d "grant_type=refresh_token&refresh_token={token}&client_id={ci}&client_secret={cs}"

Verify: New access_token and refresh_token returned.

Code Examples

Python: Authenticate and call ION API

# Input:  .ionapi credentials file path
# Output: JSON response from ION API endpoint

import json
import requests  # requests==2.31.0

def load_ionapi_credentials(filepath):
    with open(filepath, 'r') as f:
        return json.load(f)

def get_access_token(creds):
    resp = requests.post(creds['pu'], data={
        'grant_type': 'password',
        'username': creds.get('saession', creds.get('saak', '')),
        'password': creds.get('sapassword', creds.get('sask', '')),
        'client_id': creds['ci'],
        'client_secret': creds['cs'],
    }, timeout=30)
    resp.raise_for_status()
    return resp.json()

def call_ion_api(base_url, tenant, endpoint, token):
    url = f"{base_url}/{tenant}/{endpoint}"
    resp = requests.get(url, headers={
        'Authorization': f"Bearer {token}",
        'Accept': 'application/json',
    }, timeout=60)
    if resp.status_code == 429:
        retry_after = int(resp.headers.get('Retry-After', 60))
        raise Exception(f"Rate limited. Retry after {retry_after}s")
    resp.raise_for_status()
    return resp.json()

creds = load_ionapi_credentials('my_app.ionapi')
tokens = get_access_token(creds)
result = call_ion_api(creds['iu'], creds['ti'],
    'ifsservice/usermgt/v2/users/me', tokens['access_token'])

JavaScript/Node.js: Compass V2 query with pagination

// Input:  .ionapi credentials, SQL query string
// Output: All query result rows (paginated)

const fs = require('fs');
const axios = require('axios'); // [email protected]

async function compassQuery(ionapiPath, sql) {
  const creds = JSON.parse(fs.readFileSync(ionapiPath, 'utf8'));
  const tokenResp = await axios.post(creds.pu, new URLSearchParams({
    grant_type: 'password',
    username: creds.saession || creds.saak,
    password: creds.sapassword || creds.sask,
    client_id: creds.ci,
    client_secret: creds.cs,
  }).toString(), { headers: { 'Content-Type': 'application/x-www-form-urlencoded' } });

  const token = tokenResp.data.access_token;
  const baseUrl = `${creds.iu}/${creds.ti}`;
  const headers = { Authorization: `Bearer ${token}` };

  // Submit query
  const jobResp = await axios.post(`${baseUrl}/v2/compass/jobs`, sql,
    { headers: { ...headers, 'Content-Type': 'text/plain' } });
  const queryId = jobResp.data.queryId;

  // Poll with backoff
  let status = 'RUNNING', delay = 1000;
  while (status !== 'FINISHED' && status !== 'FAILED') {
    await new Promise(r => setTimeout(r, delay));
    const s = await axios.get(`${baseUrl}/v2/compass/jobs/${queryId}`, { headers });
    status = s.data.status;
    delay = Math.min(delay * 2, 30000);
  }

  // Paginate results
  const allRows = [];
  let offset = 0, limit = 10000, hasMore = true;
  while (hasMore) {
    const r = await axios.get(`${baseUrl}/v2/compass/jobs/${queryId}/result`,
      { params: { resultFormat: 'application/x-ndjson', offset, limit }, headers });
    const rows = r.data.split('\n').filter(Boolean).map(JSON.parse);
    allRows.push(...rows);
    hasMore = rows.length === limit;
    offset += limit;
  }
  return allRows;
}

cURL: Quick authentication test

# Input:  .ionapi credentials (manually extracted)
# Output: User info JSON confirming successful auth

TOKEN=$(curl -s -X POST "{tokenEndpoint}" \
  -d "grant_type=password&username={accessKey}&password={secretKey}&client_id={clientId}&client_secret={clientSecret}" \
  | jq -r '.access_token')

curl -s "https://inforos-{region}.inforcloudsuite.com/{tenant}/ifsservice/usermgt/v2/users/me" \
  -H "Authorization: Bearer $TOKEN" | jq .

Data Mapping

ION API Gateway Data Patterns

Data Type Gotchas

• Compass NDJSON vs CSV: NDJSON preserves data types (numbers, booleans, nulls) while CSV treats everything as strings. Use NDJSON for programmatic consumption. [src6]
• BOD date formats: ION Connect BODs use ISO 8601, but some legacy Infor applications store dates as integer offsets — ION Mapper transformation required. [src8]
• .ionapi credential field names: Older files use saession/sapassword; newer versions may use saak/sask. Code must handle both. [src4]

Error Handling & Failure Points

Common Error Codes

Failure Points in Production

• Silent .ionapi credential rotation: When the service account is regenerated, the existing file becomes invalid but old tokens still work until expiry. Fix: Monitor for 401 errors and trigger credential file reload. [src3]
• Compass results expire after ~20 hours: Nightly batch jobs that don't retrieve results until next business day lose data. Fix: Retrieve and persist results immediately after query completion. [src6]
• Buffered policy 10 MB limit truncates responses: Endpoints with transformation policies silently truncate large responses. Fix: Remove buffered policies for large-payload endpoints or paginate. [src7]
• Timeout mismatch between gateway and backend: Gateway default is 1 minute, but some M3 programs take 2-3 minutes. Fix: Configure endpoint-level timeout extension (max 5 min). [src7]
• Rate smoothing introduces unpredictable latency: When delayAfterCount is exceeded, P99 latencies spike without returning errors. Fix: Monitor response times, not just error rates; implement circuit breaker. [src5]

Anti-Patterns

Wrong: Hardcoding the OAuth token endpoint URL

# BAD — hardcoded token URL breaks when migrating between tenants or regions
TOKEN_URL = "https://inforos-us.inforcloudsuite.com/MYTENANT/as/token.oauth2"

Correct: Extract token URL from .ionapi credentials file

# GOOD — token URL is tenant-specific and changes with migration
creds = json.load(open('my_app.ionapi'))
TOKEN_URL = creds['pu']  # always correct for this tenant

Wrong: Polling Compass query status in a tight loop

// BAD — burns through API quota (10K calls/min) and adds unnecessary load
while (status !== 'FINISHED') {
  const resp = await axios.get(`${baseUrl}/v2/compass/jobs/${queryId}`);
  status = resp.data.status;
}

Correct: Poll with exponential backoff

// GOOD — respectful polling with increasing intervals
let delay = 1000;
while (status !== 'FINISHED' && status !== 'FAILED') {
  await new Promise(r => setTimeout(r, delay));
  const resp = await axios.get(url, { headers });
  status = resp.data.status;
  delay = Math.min(delay * 2, 30000); // max 30s between polls
}

Wrong: Ignoring gateway timeout for long-running operations

# BAD — large data export times out at 60 seconds
response = requests.get(f"{base_url}/myapp/api/export-all",
    headers=headers, timeout=300)  # client timeout is 5 min but gateway kills at 1 min

Correct: Use Compass V2 async queries for bulk data

# GOOD — Compass handles long-running queries asynchronously
job = requests.post(f"{base_url}/v2/compass/jobs",
    data="SELECT * FROM large_table",
    headers={**headers, 'Content-Type': 'text/plain'})
query_id = job.json()['queryId']
# Poll for completion, then paginate results

Common Pitfalls

• Assuming a global rate limit exists: Unlike Salesforce or Oracle, Infor uses configurable per-endpoint throttling. Fix: Test each endpoint's throttling behavior independently or review API suite configuration. [src5]
• Using the wrong OAuth grant type: Resource Owner is correct for backend server-to-server. Authorization Code for batch jobs introduces unnecessary user interaction. Fix: Resource Owner for backends, Authorization Code for web/mobile, SAML Bearer for Ming.le-embedded apps. [src3]
• Not handling credential file format differences: The .ionapi file field names changed between versions. Fix: Check for both field name variants (saession/sapassword vs saak/sask) with fallbacks. [src4]
• Treating Compass V2 like a real-time API: Compass queries are async with ~20-hour result TTL. Fix: Use ION API Gateway REST endpoints for real-time; reserve Compass for analytics and bulk reads. [src6]
• Ignoring 10 MB buffered policy limit: API suites with SOAP-to-REST transformation silently truncate large payloads. Fix: Avoid transformation policies for high-volume endpoints, or paginate at application layer. [src7]

Diagnostic Commands

# Test authentication — obtain access token
curl -s -X POST "{tokenEndpoint}" \
  -d "grant_type=password&username={accessKey}&password={secretKey}&client_id={clientId}&client_secret={clientSecret}" \
  | jq '{access_token: .access_token, token_type: .token_type, expires_in: .expires_in}'

# Verify token validity — get current user info
curl -s -X GET "https://inforos-{region}.inforcloudsuite.com/{tenant}/ifsservice/usermgt/v2/users/me" \
  -H "Authorization: Bearer {token}" | jq .

# Test a specific API suite endpoint
curl -s -o /dev/null -w "HTTP %{http_code} — %{time_total}s\n" \
  -X GET "https://inforos-{region}.inforcloudsuite.com/{tenant}/{suite}/{endpoint}" \
  -H "Authorization: Bearer {token}"

# Check Compass query status
curl -s "https://inforos-{region}.inforcloudsuite.com/{tenant}/v2/compass/jobs/{queryId}" \
  -H "Authorization: Bearer {token}" | jq '{status: .status, rowCount: .rowCount}'

# Revoke token (cleanup)
curl -s -X POST "{revokeEndpoint}" \
  -d "token={token}&token_type_hint=access_token&client_id={clientId}&client_secret={clientSecret}"

Version History & Compatibility

When to Use / When Not to Use

Important Caveats

• Rate limits are NOT globally documented: Infor's approach is per-endpoint configurable, requiring testing or admin access to discover actual limits.
• Cloud vs on-premise are fundamentally different: Cloud uses OAuth 2.0 exclusively; on-premise supports basic auth and client certificates. Do not mix documentation.
• Compass V2 is for Data Lake reads only: Cannot write, update, or delete data in Infor applications. Use REST endpoints or BODs for writes.
• Tenant-specific URLs: Every URL contains {region} and {tenant} placeholders unique per deployment. Extract from .ionapi file.
• Information currency: Infor updates ION API capabilities with each CloudSuite release. Always verify against current release notes.