Skip to content

Troubleshooting OAuth2 Token Retrieval

Most OAuth2 problems surface when QIE requests an access token. The fastest way to diagnose them is the Test OAuth button in the Authentication Protocol section. It submits a single token request with the current configuration and shows the response, logs, and parsed values. Save any pending changes first. The cases below cover the common failures.

"Unable to retrieve token", but the response clearly contains a token

This error means QIE received a response from the token server but could not locate the access token inside it using the configured Token Path. The full response payload is included in the error text, so a response that plainly shows "access_token": "..." next to this error is the tell-tale sign: the token is there, but Token Path is not pointing at it.

Read the JSON in the error payload and set Token Path to the node path where the token actually appears. For a standard response that is /access_token. A blank or mismatched Token Path is the usual cause even though the token is obviously present.

The token works at first, then calls start failing later

QIE caches the access token until it expires. When Token Refresh is set to Refresh when token expires or Refresh based on token, the Expire Path must point at the field holding the token lifetime in seconds (typically /expires_in). If Expire Path is wrong, QIE miscalculates the expiry and either keeps using a stale token or refreshes far too often. Confirm Expire Path matches the response.

The response is not a token at all (an error object, HTML, or a 4xx)

If the payload in the error is an error message or HTML rather than token JSON, the token server rejected the request itself. Token Path is not the problem. Check:

  • Content-Type: Match what the server expects. application/x-www-form-urlencoded and application/json are not interchangeable.
  • Payload: The grant body and parameters the server requires (grant type, scopes, client identifiers).
  • Include Basic Authentication in Header?: Enable when the server expects client_id / client_secret as a Basic Authorization header rather than in the payload.
  • Static OAuth2 HTTP Headers: Add Accept: application/json if the server returns XML or HTML by default.

SMART Backend Services endpoints (Cerner, Epic, and similar)

SMART Backend Services endpoints authenticate with a signed JWT client-assertion grant, not a username/password client_credentials exchange. If Authentication is set to OAuth2 with Credentials against one of these endpoints, token retrieval fails no matter how Token Path is configured. The token server never issues a token for that grant.

Switch Authentication to OAuth2 with JWT, set the Signing Cert and the Token Config claims the vendor requires (issuer, audience/token URL, scopes), and register the matching public key with the vendor's app registration.

For step-by-step configuration walkthroughs of each grant type, see the OAuth tutorial.