Authenticate and get access

26R1 reference · Documentation-based tutorial draft · Not executed in IFS

Integration learning center

Try the flow interactively

The Example flow menu below defaults to “Request an access token.” Choose an outcome and step through it, then click a node to inspect it.

BROWSER SIMULATION · FICTIONAL DATA · NO IFS CONNECTION

A fictional client-credentials token request. Try valid credentials, a wrong secret, or a scope the client was never granted.

Next stepRun to endReset flow

Ready. Choose Next step or Run to end.

Click a node to inspect it. Highlighted arrows show the path taken; the dashed outline marks the current step. On small screens, scroll the diagram sideways.

Start

The external system holds a client ID and secret issued for a dedicated integration user. This teaching flow makes no live network call.

Read the walkthrough

Variables at the current step

No steps executed yet.

Execution trace

1. No steps executed yet.

These fictional flows illustrate a common shape. Confirm the exact endpoints, grant types, and error codes for your environment before building against them.

Outcome and prerequisites

Obtain a working access token for a dedicated integration identity, use it to call a projection API, and recognize the difference between an authentication failure and an authorization failure. You need an authorized development environment, permission to create or review an integration user, and a candidate API from API discovery.

Step-by-step: obtain and use a service token

1. Create the identity and custom IAM client

In the development environment, open IAM Clients and create a Custom Client for this integration. Use a confidential client with its service-account capability enabled for the client-credentials flow. Do not change an IFS-delivered client shared with platform components.

Record the client ID, generated service-account identity, token endpoint, and the configured realm/namespace. Store the client secret through the approved secret mechanism. Grant the resulting IFS identity only the permission sets and company/site access required for your read operation. If service-user provisioning/mapping requires an administrator in your installation, verify it before testing.

2. Build a token request in Postman

Create a private POST request to the token endpoint supplied by the administrator. The documented route has this form, but both host and realm are environment values:

https://YOUR_IFS_HOST/auth/realms/YOUR_NAMESPACE/protocol/openid-connect/token

Choose Body → x-www-form-urlencoded and add:

Key	Value
grant_type	client_credentials
client_id	Your custom client ID
client_secret	A local secret variable, not a shared collection value
scope	openid microprofile-jwt, as documented for the IFS flow; confirm installed policy

Send the request. Expect a JSON response containing access_token, token_type, and expires_in. Do not copy a documentation sample’s expiry value into your application; read the actual response. An ID token is not the bearer access token for the API.

3. Call one bounded projection read

Create a separate GET request using the exact projection/entity route proven in API Explorer. Add $top=1 and select only the approved fields. In Authorization, choose Bearer Token and use the received access token through a local secret variable. Add Accept: application/json.

Expect HTTP 200 and data within the service identity’s business scope. Compare the same record with the intended business user, not an administrator account. Save a sanitized response and the identity/permission-set names as evidence; never save the token in a public collection or screenshot.

4. Separate token failure from API failure

Failure point	Check first
Token endpoint returns invalid client	Client ID/secret, realm, and secret rotation
Grant rejected	Service account/client-credentials capability and realm policy
Token obtained, API returns 401	Access token rather than ID token, expiry, issuer/audience, environment
API returns 403	Projection/action grants plus business scope
API returns no rows	Query filters and company/site restrictions

For a server application, cache the token until shortly before its returned expiry, then request a new token. Do not rely on a refresh token being issued for every client-credentials setup. Limit automatic renewal to one attempt for an expired-token failure; endless renewal cannot fix missing authorization.

5. Test revocation and retire the lab client

Test an expired token and removal of the specific projection grant. After credential rotation, confirm the application acquires tokens using the new secret; do not assume all existing access tokens are immediately invalidated merely because the secret changed.

Clear local tokens and revoke/delete the dedicated lab credential when finished. A browser or mobile client cannot safely keep a confidential service secret; use its supported delegated authorization flow instead.

Sources: IFS IAM Clients and client-credentials request.

The concept

External calls to IFS Cloud APIs use the configured authentication flow, commonly OAuth 2.0 bearer tokens representing either a service identity or an authorized user. IFS Cloud environments typically validate these tokens against the environment’s configured identity provider; confirm the exact token endpoint, supported grant types, and issuer for your environment rather than assuming a shared default.

Two identities matter here, and confusing them is a common source of access problems:

• The client — the registered application/credential the external system authenticates as (commonly a client ID and secret, using a client-credentials-style grant for machine-to-machine calls).
• The integration user — the IFS Cloud user the resulting token acts as, whose permission sets determine which projections, entity sets, and operations are actually reachable.

A valid token proves who is calling. It does not by itself prove what they are allowed to do — that is a separate, permission-set-driven check on each API call.

A worked scenario

An external handover tool needs to read and occasionally update handover records. Before writing a client, a dedicated integration user is created (not a shared personal login), granted only the permission sets that cover the handover projection’s read and update operations, and a client credential is registered for that identity. The external system requests a token, caches it, and reuses it until it is close to expiry rather than requesting a fresh token on every call.

Work through it

1. Identify or request a dedicated integration user — do not reuse a personal or shared interactive account.
2. Grant only the permission sets needed for the specific projections and operations in scope; confirm this with permission sets.
3. Register the client credential for that identity and record its scope.
4. Request a token, store it in memory (not logs), and reuse it until it is close to expiry.
5. Call the target API with an Authorization: Bearer <token> header and confirm the response matches an authorized, not merely authenticated, request.

Try it yourself

An external system receives HTTP 401 on every call, including ones it previously expected to succeed after a credential rotation. Diagnose the likely cause before checking permission sets.

See a suggested answer

A 401 (as opposed to 403) generally means the request was not accepted as authenticated at all: an expired, malformed, or revoked token, or a token request that itself failed after the rotation. Check whether the client is still requesting tokens successfully and whether it is using the new secret, before investigating permission sets — those would surface as 403, not 401.

Check your understanding

Treating a 403 as a reason to grant broader permission sets than the task actually needs. A 403 means the request was authenticated but not authorized for that specific operation; the fix is to confirm the intended operation and grant exactly the permission set that covers it, not to over-grant until the error disappears.

Expected result: a written diagnosis distinguishing 401 from 403 causes, and the specific permission set you would check or request.

Cleanup: none; this exercise changes no IFS data.

Sources and review status

IFS Cloud technical documentation, understand permission sets. Source consulted 2026-09-23. The scenario and exercise are original fictional examples. Token endpoint details, exact grant types, and specific error payloads are environment- and deployment-specific and have not been verified against a live IFS environment; confirm them against your environment’s own identity provider configuration before implementation.

Choose the identity for a new integration

Separate interactive sign-in from unattended processing. A user-facing application needs a supported user authorization flow; a background worker needs an explicitly registered service identity and the supported grant for that use case. OpenID Connect identity information and an OAuth access token have different purposes: do not send an ID token to a business API simply because it contains the user’s name.

Before configuring a client, record issuer, token endpoint, intended audience, scopes, redirect requirements where applicable, and IFS permission/business-data scope. Obtain these from the installed IAM configuration. A browser-captured administrator token is useful neither as a permanent credential nor as evidence that the intended integration identity has access.

Test expiry, secret rotation, revoked access, and another user’s data scope. Keep token values out of screenshots and saved collections. If using an intermediary, validate both identities described in Azure API Management; for a low-code client, also check Power Apps connection sharing.