Documentation

FAQ & Troubleshooting

Answers to common questions and solutions to frequent issues.

Frequently Asked Questions

General Questions
Common questions about using Signify iD for authentication

Troubleshooting

Redirect URI Mismatch

Error: redirect_uri_mismatch

This error occurs when the redirect URI in your request doesn't match any registered URIs for your client.

Solution: Ensure the redirect URI in your authorization request exactly matches one registered in your client settings, including protocol, domain, port, and path.

typescript
// Check your redirect URI matches exactly
const REDIRECT_URI = 'http://localhost:3000/callback';  // ✅
const REDIRECT_URI = 'http://localhost:3000/callback/'; // ❌ Trailing slash
const REDIRECT_URI = 'https://localhost:3000/callback'; // ❌ Wrong protocol

Access Token Expired

Error: token_expired

The access token has expired and needs to be refreshed.

Solution: Use your refresh token to obtain a new access token before it expires.

typescript
1// Implement automatic token refresh
2async function fetchWithAuth(url: string, options: RequestInit) {
3  let response = await fetch(url, {
4    ...options,
5    headers: {
6      ...options.headers,
7      Authorization: `Bearer ${accessToken}`,
8    },
9  });
10
11  if (response.status === 401) {
12    // Token expired, refresh it
13    accessToken = await refreshAccessToken();
14    
15    // Retry the request
16    response = await fetch(url, {
17      ...options,
18      headers: {
19        ...options.headers,
20        Authorization: `Bearer ${accessToken}`,
21      },
22    });
23  }
24
25  return response;
26}

Invalid State Parameter

Error: invalid_state

The state parameter in the callback doesn't match the one sent in the authorization request.

Solution: Store the state parameter before redirecting to OAuth, then validate it on callback.

typescript
1// Generate and store state before OAuth redirect
2const state = crypto.randomUUID();
3sessionStorage.setItem('oauth_state', state);
4
5// On callback, validate the state
6const callbackState = new URLSearchParams(window.location.search).get('state');
7const storedState = sessionStorage.getItem('oauth_state');
8
9if (callbackState !== storedState) {
10  throw new Error('Invalid state - possible CSRF attack');
11}
12
13sessionStorage.removeItem('oauth_state');

Session Not Found

Error: session_not_found

The session has been revoked, expired, or never existed.

Possible causes:

  • User logged out from another device
  • Session expired due to inactivity
  • Administrator revoked the session
  • Cookies were cleared

Solution: Redirect the user to login to create a new session.

CORS Errors

Error: CORS policy blocked request

Cross-Origin Resource Sharing (CORS) is blocking your API requests.

Solution: Ensure your domain is added to the allowed origins in your client settings. Token exchange should happen server-side, not from the browser.

Debugging Tips

Check Network Requests

Use browser DevTools → Network tab to inspect OAuth redirects and API calls. Look for error responses and verify request parameters.

Verify Environment Variables

Double-check that your Client ID, Client Secret, and Redirect URI are correctly set in your environment configuration.

Check Console Logs

The Signify iD SDK logs helpful debugging information to the console in development mode.

Review Audit Logs

Check the Audit Logs in your Signify iD dashboard for detailed information about authentication attempts and errors.

Getting Help

Need more help?

If you're still having issues after reviewing this documentation, you can:

  • Check our GitHub repository for known issues
  • Join our Discord community for peer support
  • Contact support@signifyid.com for direct assistance