Common OAuth Errors

The following table summarizes frequently encountered OAuth 2.0 errors and their most likely causes.

Example: Using A JWT Assertion As An Access Token

Symptom

HTTP/2 401
www-authenticate: Bearer error="invalid_token"

Cause

Your system used the JWT assertion generated by jwtoken.html as if it were an OAuth access token.

Fix

Exchange the JWT assertion for an OAuth access token before calling any API.

curl -X POST "https://sandbox.healthgorilla.com/oauth/token" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d 'grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer' \
-d 'assertion=YOUR_JWT_ASSERTION' \
-d 'scope=patient360 user/*.*'

Use the returned access token in the Authorization header for all API requests.

Example: Invalid Client ID During Token Exchange

Symptom

invalid_client

or

improper client id

Cause

The iss or sub claim in the JWT assertion does not match the assigned client ID. This commonly occurs when an email address is used instead of the client ID.

Fix

Set the following values in the JWT assertion:

• iss = YOUR_CLIENT_ID
• sub = YOUR_CLIENT_ID Never use an email address in the sub claim.

Example: Environment Mismatch

Symptom

Authentication succeeds in one environment but fails in another.

Cause

A JWT assertion generated for one environment was sent to the token endpoint for a different environment. The aud claim does not match the token URL.

Fix

Match the audience and token URL exactly.

• Sandbox environment token URL and aud: https://sandbox.healthgorilla.com/oauth/token
• Production environment token URL and aud: https://api.healthgorilla.com/oauth/token

Example: Token Exchange Fails Without A Response

Symptom

No response body is returned from the token endpoint.

Cause

The JWT assertion is malformed or expired. Silent failures often indicate one of the following:

• exp timestamp is in the past
• aud value does not match the token URL
• Assertion was truncated or corrupted when copied

Fix

Generate a new JWT assertion immediately before token exchange and verify:

• exp is in the future
• aud matches the token endpoint
• The full assertion value was copied without modification

Example: Using An Expired JWT Assertion

Symptom

Token exchange fails after a short delay.

Cause

JWT assertions generated by jwtoken.html include short-lived timestamps and expire quickly.

Fix

Generate a fresh JWT assertion immediately before calling /oauth/token. Assertions cannot be reused after expiration.

Example: Postman UI Does Not Match Instructions

Symptom

Postman screenshots or variable locations do not match the current application UI.

Cause

Postman updates may change layout and labeling without notice.

Fix

Confirm the following:

• Environment variables are stored in the Environment panel
• The JWT assertion is pasted into the correct request field
• The token request uses application/x-www-form-urlencoded body encoding

Example: Confusion About grant_type Values

Symptom

Token exchange fails when experimenting with different grant_type values.

Cause

Parameters from multiple OAuth flows were combined, or an unsupported grant_type string was used.

Fix

Use exactly one supported pattern per request. JWT Bearer flow:

• grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer
• assertion=YOUR_JWT_ASSERTION

Client Credentials flow:

• grant_type=client_credentials
• client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer
• client_assertion=YOUR_JWT_ASSERTION

Do not invent alternative grant_type values or mix parameters from different flows.