Troubleshoot authentication issues

Most external systems require authentication for system-to-system communication. The adapter must be configured to use the authentication method the external system expects. The three most common methods are basic authentication (username and password), static token (such as an API key or personal access token), and dynamic two-step token (such as OAuth).

Configure authentication

Authentication is primarily configured in the authentication section of theItential Platform service instance configuration inItential Platform Admin Essentials. The most commonly changed properties are auth_method, username, password, token, auth_field, and auth_field_format.

For basic authentication and static token, updating the service instance configuration is typically all that is required.

For dynamic two-step token authentication, you may also need to update the endpoint configuration in the .system entity at /adapter-home-dir/entities/.system. The changes that are most commonly needed are:

getToken action in action.json — defines the call used to retrieve a token. Fields that may need updating include entitypath, requestDatatype, responseDatatype, header overrides, and sso (if the token endpoint is on a different host).

Schema files for getToken — the request schema defines what data is sent on the token request; the response schema defines where in the response the adapter should look for the token. You may need to add fields to the request schema or set the correct external_name for the token field in the response schema.

For detailed examples of each authentication method and configuration pattern, see the Authentication section.

Enable auth logging

When standard debug logging is not enough to diagnose an authentication problem, enable auth_logging in the adapter properties inItential Platform Admin Essentials. This adds two additional log entries that include credential and header information that is intentionally omitted from normal debug logs:

FULL_REQUEST — all call options including authentication headers and the full URL. This is the most useful log for diagnosing why authentication is failing.

FULL_BODY — the complete request payload as it exists immediately before the call is made, including any authentication data added to the body.