Common Mistakes

A collection of integration errors that consistently come up during development. Each entry describes what goes wrong, why, and how to fix it.

1. redirect_uri Mismatch

Symptom: The OAuth flow fails with an invalid_request error after the admin approves the consent screen. The browser is redirected to an error page instead of your callback URL.

Cause: The redirect_uri you pass in the authorization URL (or in the token exchange request) does not exactly match one of the Redirect URLs registered in Developer Configuration. Common sources of mismatch:

Fix:

• Copy the redirect_uri value exactly from Developer Configuration.
• Use a constant in your code for the redirect URI. Do not build it from parts at runtime.
• Make sure the same constant is used in both the authorization URL (Step 1) and the token exchange request body (Step 3). Any difference between the two also causes the exchange to fail.

2. Using localhost as redirect_uri

Symptom: The Developer Configuration form rejects the URL with a validation error when you try to save http://localhost:3000/oauth2/crm/callback as a Redirect URL.

Cause: Developer Configuration requires a valid domain with a real TLD (e.g. .com, .app). localhost has no TLD and is rejected by the form. You cannot save it, and therefore cannot use it in an OAuth flow.

Fix: Use a tunneling tool to expose your local server under a public HTTPS domain, then register that URL instead:

• ngrok: ngrok http 3000 gives you a URL like https://abc123.ngrok-free.app. Register https://abc123.ngrok-free.app/oauth2/crm/callback.
• Cloudflare Tunnel: Similar approach, can be tied to a stable custom domain.

Register the tunneled URL in Developer Configuration alongside your staging and production URLs. You can have multiple redirect URLs registered at the same time.

Note: ngrok free-tier URLs change every time you restart the tunnel. Either use a paid ngrok plan for a stable subdomain, or re-register the new URL in Developer Configuration after each restart.

3. Using the Wrong Base URL for Token Exchange

Symptom: POST /api/oauth2/token/exchange returns a connection error, 404 Not Found, or an unexpected response.

Cause: The token exchange endpoint is on a different host from all other API calls:

Using https://dev.askyura.com/api/oauth2/token/exchange for the exchange, or https://api.askyura.com for regular API calls, will both fail.

Fix: Store the two base URLs as separate constants and use them in the right places:

const CRM_OAUTH_BASE_URL = "https://api.askyura.com"; // token exchange only
const CRM_API_BASE_URL = "https://dev.askyura.com";   // all other API calls

// Token exchange
await fetch(`${CRM_OAUTH_BASE_URL}/api/oauth2/token/exchange`, { ... });

// Regular API call (example)
await fetch(`${CRM_API_BASE_URL}/api/v1/conversations`, { ... });

See API Requests for the full base URL reference.

4. Using the Wrong Base URL for Regular API Calls

Symptom: API calls for conversations, contacts, messages, etc. return 404 Not Found or fail to connect.

Cause: Same split as above, developers who notice api.askyura.com in the OAuth docs sometimes use it for all subsequent calls. All CRM REST API endpoints (contacts, conversations, messages, channels, agents) live under https://dev.askyura.com/api/.

Fix: Use https://dev.askyura.com as the base for every API call except token exchange. See the table in mistake #3 above.

5. Not Passing redirect_uri in the Token Exchange Request

Symptom: Token exchange fails with invalid-exchange-token-payload even though the authorization code is fresh and the credentials are correct.

Cause: The token exchange endpoint requires redirect_uri in the request body, and it must match the one used during the authorization step. Omitting it causes the server-side validation (handled by Ory Hydra) to reject the request.

Fix: Always include redirect_uri in the exchange body, and make sure it is identical to the one in the authorization URL:

{
  "client_id": "<YOUR_CRM_CLIENT_ID>",
  "client_secret": "<YOUR_CRM_CLIENT_SECRET>",
  "code": "<RECEIVED_CODE>",
  "redirect_uri": "<SAME_URI_USED_IN_AUTH_URL>"
}

See Step 3: Exchange the Code for an Access Token.