Troubleshooting Kinde Management API

If you’re getting unexpected errors from the Kinde Management API, use this guide to identify the cause and apply a fix.

Token exchange errors

Link to this section

Not found

Link to this section

Error response:

HTTP/1.1 404 Not Found

Solution:

Make sure you have copied the correct Kinde domain and client ID. Even if you have set up a custom domain, you must use the original Kinde domain in your request (e.g. https://<your_subdomain>.kinde.com).

1. Go to Settings > Applications and open your M2M application.
2. Select App keys.
3. Copy the Domain, Client ID and Client Secret and update them in your request.

Authentication failed

Link to this section

Error response:

{
  "error": "invalid_client",
  "error_description": "Client authentication failed (e.g., unknown client, no client authentication included, or unsupported authentication method)."
}

Solution:

Verify that the Client Secret is copied exactly, with no typos.

Missing audience

Link to this section

Error response:

HTTP/1.1 403 Forbidden

{
  "error":"invalid_request",
  "error_description":"The request is missing a required parameter, includes an invalid parameter value, includes a parameter more than once, or is otherwise malformed. Requested audience 'https://<your_subdomain>.kinde.com/api' has not been whitelisted by the OAuth 2.0 Client."
}

Solution:

Add the correct audience parameter to your token request. The value must be your Kinde domain followed by /api. Even if you use a custom domain, the audience value must still use your https://<your_subdomain>.kinde.com domain.

To find your Kinde domain:

1. Go to Settings > Applications and open your M2M application.
2. Select Details.
3. Copy the Domain value and use it in your request as follows:

curl --request POST \
  --url 'https://<your_subdomain>.kinde.com/oauth2/token' \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data grant_type=client_credentials \
  --data 'client_id=<your_m2m_client_id>' \
  --data 'client_secret=<your_m2m_client_secret>' \
  --data 'audience=https://<your_subdomain>.kinde.com/api'

Scope is missing

Link to this section

Error response:

HTTP/1.1 403 Forbidden

{
  "error":"invalid_scope",
  "error_description":"The requested scope is invalid, unknown, or malformed. The OAuth 2.0 Client is not allowed to request scope '<scope>'."
}

Solution:

Your M2M application does not have the required scope enabled for the endpoint you’re calling. Add the missing scope to your application and then get a new access token before retrying.

1. Go to Settings > Applications and open your M2M application.
2. Select APIs in the menu.
3. In the Kinde Management API entry, select the three dots menu and select Manage scopes.
4. Enable the missing scopes.
5. Select Save.

For a full list of available scopes, see API scopes.

API request errors

Link to this section

Route not found

Link to this section

Error response:

{
  "errors": {
    "code": "ROUTE_NOT_FOUND",
    "message": "The requested API route does not exist"
  }
}

Solution:

The API route you’re calling does not exist. Check the Management API reference for the correct endpoint path and correct any typos.

Scope missing error

Link to this section

Error response:

{
  "errors": [
    {
      "code": "SCOPE_MISSING",
      "message": "Scope is missing: read:environments"
    }
  ]
}

Solution:

Your M2M application does not have the required scope enabled for the endpoint you’re calling. Add the missing scope to your application and then get a new access token before retrying.

1. Go to Settings > Applications and open your M2M application.
2. Select APIs in the menu.
3. In the Kinde Management API entry, select the three dots menu and select Manage scopes.
4. Enable the missing scopes.
5. Select Save.

For a full list of available scopes, see API scopes.

Other errors

Link to this section

API request returns null or empty

Link to this section

Solution:

The data you’re requesting exists but isn’t included in the token by default. Add custom claims to include it:

1. Go to Settings > Applications and open the relevant application.
2. Select Tokens in the menu.
3. Scroll to the Token customization section.
4. Select Customize on the Access or ID token type and enable the claims or properties you need.
5. Select Save.

For more information, see Token customization.

Too many requests

Link to this section

Error response:

HTTP/1.1 429 Too Many Requests
RateLimit-Reset: 30

Solution:

You’ve exceeded the API rate or concurrency limit. Read the RateLimit-Reset header value to get the number of seconds before the limit resets, then wait before retrying.

See API rate limits for a full breakdown of limits and a recommended retry strategy using exponential backoff.

Get support

Link to this section

If you’re still having problems:

• Contact Kinde support
• See the common error codes reference