Troubleshoot OAuth API key errors

Last updated: Nov 27, 2023

You may run into some of these errors when trying to authenticate an OAuth API key.

Example error

An error response may look like this:

Example: Auth error response
"error": "invalid_request",
"error_description": "",
"error_uri": ""

Common error descriptions

You may come across any of these error_descriptions. Review the notes to learn the reasons for these errors and instructions for how to fix them.

Error description
If you receive a blank error_description, confirm that all the parameter values (e.g., aud, alg, jti) are correct. Review the expected values if you need a refresher.
x-www-form-urlencoded content-type required
The content-type header needs to be application/x-www-form-urlencoded when POSTing to the /v2/auth/token endpoint.
Missing grant_type parameter or The grant_type parameter should equal 'client_credentials'
The request body needs a key of grant_type set to client_credentials per the OAuth 2.0 specification.
Missing client assertion type or Invalid client assertion type
The request body needs the client_assertion_type parameter populated with urn:ietf:params:oauth:client-assertion-type:jwt-bearer. Learn about rfc7523.
Missing client assertion
The request body needs the parameter client_assertion with the value of your signed assertion.
JWT header kid property is required
We require that a kid property be sent in the header of your signed assertion. This allows you to use multiple public keys or do key rotations. Many libraries support this functionality out of the box.
Public key not found, check client_id, kid and Redox dashboard settings
Something is wrong with the configuration for your API key. You may see this error if any of these steps fail:
(a) Pull the client_id out of the signed JWT iss property;
(b) look up the corresponding public keys from the JWKS URL or dashboard; and
(c) use the kid property from the JWT header to find the right public key to verify with.
If this error appears, you may have the wrong client_id in your assertion or you may have forgotten to click the Save Changes button when setting public keys in the dashboard.
Unexpected X claim value
There are a few claim values or header values that could be missing or not formatted correctly. This could be any of these values
"X" claim timestamp check failed
The timestamp for any of these claim values might fail and return this type of error:
"iat" claim timestamp check failed
It's possible that the iat timestamp failed. An additional message may categorize the issue:
(it should be in the past)
(too far in the past)
Redox expects the iat parameter value to be within the past 5 minutes. We allow a clock skew of 10 seconds, so if you keep receiving this error, you may want to check that your system clock is working as expected.
JWTs must have three components
JWT is malformed