Skip to main content
Oath Inc.

3 API OAuth Troubleshooting

This document describes various errors you may encounter with OAuth, and troubleshooting tips to resolve them. 

Invalid Request error

You will see this error if there is a problem with any of the access_token request data.

  • Make sure all parameters are spelled correctly (ex: scope, grant_type, client_assertion, realm, redirect_uri, client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer, etc.)
  • If using JWT, make sure the algorithm value is explicitly set as HS256, etc. Some libraries don't send alg value if default value is used.
  • If you see the following error, then set alg value to fix it.
"error_description": "No enum constant org.forgerock.json.jose.jws.JwsAlgorithm.none"
"error": "invalid_request"

If you take the 1st part of JWT header and base64 decode it, you'll see that the alg value is missing:


Sample fix (using jose4j sample):

JsonWebSignature jws = new JsonWebSignature();

After fixing, if you take the 1st part of the JWT header and base64 decode it, then you'll see this:


If you are seeing the error below for an introspect call, then make sure you are passing Authorization Bearer header:

 "error_description": "unable to process request",
  "error": "invalid_request"

Invalid Client error

You may see the invalid client error if your JWT assertion is not correct (e.g., the JWT is expired or invalid, audience wrong, etc.), the client id is not found, or the client_id or secret are invalid.

  • If you see the JWT expired error, make sure the jwt claims values "exp" and "iat".
  • Both values should be in seconds (EPOC time) and 'exp' should be in future but it should be less than server side configured time (i.e., 24 hrs).
  • Make sure the client_secret used to sign the JWS is same as the one you have received.
{"error_description":"JWT is has expired or is not valid","error":"invalid_client"}

Note: "exp" and "iat" values should be numeric. Do not set them as strings. "exp" value should be less than 24 hrs (preferable time is currentTime + 600 (i.e., 10 minutes)). Do not use currentTime + (24 * 60 * 60). You may get a "JWT is expired or is not valid" error.

  • If you see the audience error below, then make sure the audience value is correct:
"error_description": "Audience validation failed",
 "error": "invalid_client"

Fix  the 'aud' value in claim. aud should be:


where is id for testing and for production and <yourrealm> is "aolcorporate/aolexternals". Make sure all parameters are lowercase (e.g., realm).

If you see the error below, then check 'sub' value in claim and also the secret used to sign JWS(client_secret). They should match the credentials you received.

"error_description": "Client authentication failed",
"error": "invalid_client"

Things to check:

  1. Make sure realm value is correct.
  2. Make sure client_id, client_secret used in JWT are correct.
  3. Make sure client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer (check for typos in value).

Invalid Scopes

Check the value you are passing for scope and the value configured for your client credentials. If the passed scope value is not configured for that client_id, then you will see the error below. Check for any typos, too:

"error_description": "Unknown/invalid scope(s): [introspects]",
"error": "invalid_scope"

Unsupported Grant Type

You'll receive this error if the grant_type value is not one of the allowed list (client_credentials|password|refresh_token|authorization_code). Check for any typos in grant_type value.

"error_description": "Grant type is not supported: client_credential",
"error": "unsupported_grant_type"

Invalid Grant

If you are exchanging code for access_token and see this error then the code provided might be wrong or expired. Make sure it is generated for the same client_id and realm combinations. Make sure you didn't alter the code you received in authorize redirect call.

"error_description": "The provided access grant is invalid, expired, or revoked.",
"error": "invalid_grant"

If you are getting access_token using refresh_token and see below error then either refresh_token value is wrong or it has expired. Check for any typos or truncations. Make sure the refresh_token used is for the same client_id, realm and scope combinations.

"error_description": "grant is invalid",
"error": "invalid_grant"

Invalid Token

If you are making introspect call or userinfo call and see the error below, make sure you are passing the Authorization header Bearer token value. Make sure it is correct (no typos and no truncations). Make sure it is generated for the same realm. If it still doesn't work, then it might have expired or revoked. Try to get another fresh Bearer token.

"error_description": "The access token provided is expired, revoked, malformed, or invalid for other reasons.",
"error": "invalid_token"

Unauthorized Client

If you are making a userinfo call and see the error below, the Bearer token used might be generated for a client that is not in the same realm. Make sure realm value is correct. Check for any typos in the realm value.

"error_description": "Not able to get client from OpenAM",
"error": "unauthorized_client"

Insufficient Scope

If you are making an introspect call and see this error, the Bearer token might not have generated for introspect scope. Make sure the access_token you generated to use as Bearer token has introspect scope.

"error_description": "request is not authorized for introspection",
"error": "insufficient_scope"

Server Error

If data is not in the expected format or the flow is not supported (or some other reason), you may see this error. For access_token API check that client_assertion has the right JWT value.

"error_description": "Internal Server Error",
"error": "server_error"

Things to check:

  1. Make sure all requested parameters are passed.
  2. Check for typos in parameters.
  3. Make sure all parameters are in lowercase.
  4. Check format of values like JWT (includes header, claims, signature). No truncations, etc.
  5. If grant_type is client_credentials then client_assertion_type and client_assertion are required.
  6. If grant_type is authorization_code then code is required.
  7. If grant_type is refresh_token then refresh_token is required.
  8. Make sure "exp" and "iat" in JWT claims are numeric values. Do not set them as strings.

If you are making a userinfo call and see this error, make sure the API endpoint is correct and that you are using the correct realm value.