API Troubleshooting Guide

🔒 Authentication Error: Invalid or Modified Scope

Symptom
Fail to get a proper auth token.

Possible Cause
Our API enforces a single, fixed scope. If you try to change it, or mistype it, the authorization server will reject your request. This scope will give you full access to the API.

Fixed scope:
urn:zitadel:iam:org:project:id:314876184947078893:aud

Resolution

1. Use the exact scope value
   Do not alter or shorten the string. For example, your token request must include:

   curl -X POST https://auth.questback.com/oauth/token -d 'grant_type=client_credentials' -d 'scope=urn:zitadel:iam:org:project:id:314876184947078893:aud' -u CLIENT_ID:CLIENT_SECRET
   

   bash
2. Check for typos or encoding issues
   • No extra spaces, missing colons, or URL-encoding of :.
   • If you’re building the URL programmatically, verify your string literal exactly matches the fixed scope.

🔒 Authentication Error: Invalid Client ID (404 Not Found)

Symptom
When requesting an access token with an incorrect client ID, you could receive an error like:

{"error":"invalid_client","error_description":"client not found"}

Cause
The authorization server cannot find a matching client using the provided credentials. This typically happens if:

• The CLIENT_ID is mistyped or does not exist.
• The client has been deleted or disabled in Essentials.

Resolution

1. Verify your Client ID

   • Copy the CLIENT_ID directly from the Essentials Api login setup.
   • Ensure there are no extra characters, missing letters, or spaces.

   echo -n "YOUR_CLIENT_ID" | od -c
   

   bash

2. Check the authentication endpoint

   • Confirm you’re pointing to the correct domain:
     • https://auth.questback.com/oauth/v2/token

3. Validate credentials usage

   • Use the right combination of CLIENT_ID and CLIENT_SECRET:

     curl -X POST https://auth.questback.com/oauth/v2/token -d 'grant_type=client_credentials' -d 'scope=urn:zitadel:iam:org:project:id:314876184947078893:aud' -u YOUR_CLIENT_ID:YOUR_CLIENT_SECRET
     

     bash

4. Regenerate client credentials

   • If the ID is correct but the error persists, create a new Api Login in Essentials and update your application with the new CLIENT_ID and CLIENT_SECRET.

🔒 Authentication Error: Invalid Client Secret

Symptom
When requesting an access token with an incorrect client secret, you could receive an error like:

{"error":"invalid_request","error_description":"Errors.User.Machine.Secret.Invalid"}

Cause
The authorization server could not validate the client credentials because the provided client secret is invalid. This happens if:

• The CLIENT_SECRET is mistyped, truncated, or otherwise incorrect.
• You're using credentials from the wrong client or environment.
• The secret was regenerated in the Essentials web application.

Resolution

1. Verify your Client Secret
   • Copy the CLIENT_SECRET directly from the Essentials Api login setup page.
   • Ensure there are no missing characters, extra whitespace, or URL-encoding issues.

   echo -n "YOUR_CLIENT_SECRET" | od -c
   

   bash
2. Check the client pairing
   • Confirm that you’re using the matching CLIENT_ID and CLIENT_SECRET.
   • Example:

   curl -X POST https://auth.questback.com/oauth/token -d 'grant_type=client_credentials' -d 'scope=urn:zitadel:iam:org:project:id:314876184947078893:aud' -u YOUR_CLIENT_ID:YOUR_CLIENT_SECRET
   

   bash
3. Regenerate the client secret
   • In Essentials web application, regenerate the secret for your client.
   • Update your application configuration with the new secret.