OAuth 2.0 scopes in API Gateway

OAuth 2.0 scopes control access to API Suites in API Gateway. Scopes define whether an authorized application can access a suite and are enforced at the gateway level based on token content.

OAuth 2.0 scopes provide an additional layer of authorization that governs an authorized application's API access. In API Gateway, scopes function as access gates to API Suites. A scope grants or denies access to an entire API Suite rather than controlling granular operations within that suite.

Scopes are enforced at the gateway level. When an API call arrives, the gateway checks the token scopes against the scopes required by the API Suite. If the token lacks a required scope, the gateway returns HTTP 403 Forbidden.

This topic describes the conceptual model, enforcement logic, and token behavior that apply to all scopes in API Gateway, including standard Infor scopes and custom scopes.

For procedures on configuring OAuth 2.0 scopes, see Configuring OAuth 2.0 scopes.

For procedures on creating and managing custom scopes, see Managing custom OAuth 2.0 scopes.

For information on creating and managing authorized applications, see Authorized applications.

Scope fundamentals

In OAuth 2.0, scopes can represent fine-grained actions such as read or write. In API Gateway, scopes operate at the API Suite level.

  • A scope grants access to an API Suite.
  • A token without a matching scope is denied access to the suite.
  • Scopes do not control individual operations within an API Suite.

Scope types

Table 1. Scope types
Scope type Applies to How configured on the suite Naming format
Standard Infor scopes Infor-Provisioned, Infor-Non Provisioned, and Third Party API Suites Associated through Infor Registry, an internal tool for Infor application teams Infor-{API Suite Context}
Custom scopes Non-Infor API Suites Associated through API Gateway UI User-defined

Standard Infor scopes follow the naming format Infor-{API Suite Context}. The context identifies the API Suite. For example, Infor-Mingle, Infor-IDM, and Infor-homepages-all are standard Infor scopes.

Both scope types follow the same enforcement logic. The difference is how scopes are configured on the suite.

Enforcement model

Scope enforcement in API Gateway is controlled by a two-toggle system. Both toggles must be enabled for the gateway to validate scopes for an authorized application's requests.

Two-toggle system

Scope enforcement requires these two toggles:

  1. Enable Scopes per authorized app at the tenant level
  2. Enforce Scopes at the application level

Both toggles must be enabled for scope validation.

Enable Scopes per authorized app (tenant-level)

This toggle is located under Configuration > OAuth 2.0 Settings.

Table 2. Tenant-level toggle behavior
Setting Behavior
Disabled (default) No scopes are enforced. API calls from all clients to API Suites continue to work without scope checks. This setting provides a safe fallback option. If scope enforcement causes unexpected failures, the administrator can switch this setting back to disabled.
Enabled The gateway evaluates scopes per application and suite configuration.

Enforce Scopes (application-level)

Each authorized application includes an Enforce Scopes toggle on the application details page in the Authorized Apps UI.

  • Enforce Scopes off: No scope validation occurs. All requests are allowed.
  • Enforce Scopes on: The gateway validates token scopes against API Suite requirements.

Default behavior and opting in

The scopes feature is disabled by default to maintain backward compatibility. A tenant administrator must opt in by enabling Enable Scopes per authorized app.

When a tenant enables scopes, non-Infor authorized applications created by the tenant and the ION backend service application do not automatically participate in scope enforcement.

Tenants can enable scope enforcement for these authorized applications individually at the authorized application level by turning on Enforce Scopes.

Gateway runtime scope enforcement

When Enable Scopes per authorized app is off, the gateway does not enforce scopes. All requests are allowed regardless of scope configuration. This is the default behavior.

When Enable Scopes per authorized app is on, the gateway evaluates scopes based on the application's Enforce Scopes setting and the API Suite's associated scopes.

Application with Enforce Scopes enabled:

Table 3. Application with Enforce Scopes enabled
Token includes matching scopes API Suite has scopes associated Request allowed
Yes, scopes match Yes Yes
Yes, but scopes do not match Yes No — HTTP 403 Forbidden
No scopes in token Yes No — HTTP 403 Forbidden
Yes or No No (suite has no scopes) Yes — suite does not require scopes

Application with Enforce Scopes disabled:

Table 4. Application with Enforce Scopes disabled
Condition Request allowed
Any Yes — the gateway does not enforce scopes for this application

Even if an authorized application has scopes assigned to it, the gateway does not enforce those scopes unless the Enforce Scopes toggle is enabled for that application. An application with Enforce Scopes disabled can call any API Suite, regardless of scope associations. This behavior preserves backward compatibility but is not recommended for applications that have scopes assigned.

Key rules:

  • If an application has Enforce Scopes enabled, it must include scopes in every token request. Omitting scopes causes the gateway to return HTTP 403 Forbidden.
  • If an API Suite has no scopes associated with it, the gateway allows access regardless of application-level settings.
  • Scope matching is evaluated independently for each API Suite type. A token can succeed for one API Suite and fail for another based on scope matching.

Scope enforcement by API Suite type:

Table 5. Scope enforcement by API Suite type
API Suite type Scope type used How scopes are configured on the suite
Infor-Provisioned API Suite Standard Infor scopes Enabled through Infor Registry
Infor-Non Provisioned API Suite Standard Infor scopes Enabled through Infor Registry
Third Party API Suite Standard Infor scopes Enabled through Infor Registry
Non-Infor API Suite Custom scopes Associated through API Gateway UI

All scope types follow the same enforcement logic at the gateway level.

Token behavior

Token behavior in API Gateway is based on how scopes are included in issued access tokens and how those scopes are evaluated at runtime.

Scope intersection

The scopes included in an issued access token are determined by the intersection of three sources:

  1. Scopes assigned to the authorized application
  2. Scopes requested in the token request
  3. Scopes approved during authorization or configured on the service account

The authorization server computes the intersection of these three sets. Only scopes present in all three are included in the issued token.

This means that even if scopes are configured on the authorized application, they are only included in the token if the client requests them and they are approved or configured on the service account.

Example: scope intersection

An authorized application is configured with the scopes inventory-access, pricing-access, and reporting-access.

  • The service account has inventory-access and pricing-access enabled.
  • The client requests inventory-access in the token request.

The intersection is inventory-access. The issued token contains only this scope.

With this token:

  • The application can call API Suites that require inventory-access.
  • The application can call API Suites with no scopes associated.
  • The application cannot call API Suites that require pricing-access or reporting-access.

Empty intersection and unrecognized scopes

If the intersection of the three scope sources is empty, the authorization server issues a token with no scopes.

A token with no scopes is denied access to any scope-protected API Suite with HTTP 403 Forbidden, but can access API Suites that have no scopes associated.

Scope names are case-sensitive. For example, Infor-Mingle and infor-mingle are treated as different scopes.

If the client requests a scope that does not exist or is not assigned to the authorized application, the authorization server rejects the request with an invalid_scope error and does not issue a token.

This applies to both standard Infor scopes and custom scopes. All scope names in the request must exactly match assigned scopes, including casing.

Token refresh and scope changes

When a client uses a refresh token to obtain a new access token, the authorization server recalculates the scope intersection at the time of refresh.

If scope assignments or associations have changed, the refreshed token reflects the current configuration rather than the original token.

  • If a scope was removed, it is not included in the refreshed token.
  • If a new scope was added and requested, it can be included in the refreshed token.

Refreshing a token does not guarantee the same scopes as the original token.

Ensuring correct token scopes

The gateway validates only the scopes present in the token. Consistency across all scope sources is required.

  • Backend applications: the service account must have the same scopes assigned as the authorized application, and the client must include those scopes in the token request.
  • Front-end applications: the user must approve scopes during the consent flow, and the client must request them in the authorization request.

For configuration procedures, see the relevant task topics for backend and front-end applications in Configuring OAuth 2.0 scopes.

Scope errors in token requests

Table 6. Scope error scenarios
Scenario Result
Client omits a valid scope Token is issued without the scope. The application loses access to the associated API Suite.
Client requests a scope that does not exist or is not assigned Token request fails with invalid_scope. No token is issued.
Client requests a scope with incorrect casing Token request fails with invalid_scope. No token is issued.

Verifying token contents

  • Credentials file: shows scopes assigned to the authorized application, but not the scopes in the issued token.
  • Token response: the scope field in the token response shows the scopes included in the token and is the authoritative source.

After changing scope assignments or associations, all applications must request a new access token. Existing tokens may not reflect the updated configuration.

Failing to obtain a new token is a common cause of unexpected HTTP 403 errors after scope changes.

Scope behavior by OAuth 2.0 grant type

Scope handling varies depending on the OAuth 2.0 grant type used by the application.

For the mapping between application types and grant types, see Authorized applications.

SAML Bearer grant

  • The SAML assertion includes the allowed API Gateway scopes for the client based on the Infor Registry configuration for the client application type.
  • For example, the Infor Homepages application type has the Infor-homepages-all scope associated in Infor Registry. The SAML assertion issued to the application includes this scope.
  • If the scopes in the access token do not match the scope required by the target API Suite, the gateway returns HTTP 403 Forbidden.

Authorization Code grant

  • The client sends a space-delimited list of scopes in the authorization request.
  • The authorization server prompts the user for consent based on the requested scopes and grants approval for the appropriate scopes.
  • If the scopes in the access token do not match the scope required by the target API Suite, the gateway returns HTTP 403 Forbidden.

Implicit grant

  • Associate the required scopes with the authorized application in Infor Registry or the API Gateway user interface.
  • Scopes associated with the authorized application are included in the QR code or the .ionapi credentials file. The authorized application must support the current .ionapi file format.
  • When making an authorization request, send the list of scopes that correspond to the API Suites the application needs to access.

Resource Owner grant (backend applications)

  • Associate the required scopes with the Infor OS Security service account configured for the backend application.

Device Authorization grant (headless applications)

  • When the headless application initiates device authorization, it can optionally send the scopes allowed for the application.

OAuth 2.0 scopes best practices

Token management

  • Obtain an access token when you first access the API or when the existing token expires.
  • Use the expires_in value as a guideline for token lifetime. For example, if the token expires in 2 hours, continue using it for approximately 1 hour 55 minutes, then obtain a new token.
  • Obtaining an access token for each API call is an anti-pattern and must be avoided.
  • If you receive a refresh token along with an access token, use the refresh token to obtain a new access token when the current one expires.
  • For clustered applications, implement a common OAuth 2.0 token management layer that obtains and securely stores tokens.

Access control design

  • Follow the principle of least privilege. Assign only the scopes that each application requires.
  • Group related API Suites under a single scope when they serve the same business function. For example, use a single order-management scope for OrderEntry, OrderFulfillment, and OrderReturns suites.
  • Use separate scopes per API Suite when independent grant or revoke control is required.
  • Review scope assignments periodically to remove unnecessary permissions.
  • When an application calls both Infor and Non-Infor API Suites, verify that the token includes the correct scope type for each suite. Standard Infor scopes and custom scopes are evaluated independently.

Scope lifecycle management

  • Audit custom scopes quarterly to identify unused or redundant scopes.
  • Remove all scope associations, including API Suites and authorized applications, before deleting a custom scope.
  • Document the business purpose of each scope so future administrators understand why it exists.
  • Track scope changes through audit events for compliance and change management.
  • Consolidate scopes that serve similar purposes to stay within the 100-scope tenant limit.

Security

  • Always enable Enforce Scopes on any authorized application that has scopes assigned. If it is disabled, the gateway does not validate scopes for that application.
  • Treat scope configuration changes as security-sensitive operations that require change management review.
  • Coordinate scope changes with application owners to avoid service disruptions. Removing a scope from an application or service account immediately affects token issuance.
  • Monitor for unauthorized scope associations through audit events.
  • Test scope changes in non-production environments before applying them to production.
  • After any scope change, verify that affected applications can still obtain tokens with the expected scopes before considering the change complete.