Troubleshooting

Cause: The redirect URI in your code doesn't match the one configured in your OAuth client.

Solution:

1. Go to Applications → Your App → Settings
2. Check the Redirect URIs field
3. Ensure it exactly matches your code (including trailing slashes)

// Must match exactly
redirectUri: 'https://yourapp.com/callback' // No trailing slash

Cause: Your origin isn't in the allowed origins list.

Solution:

1. Go to Applications → Your App → Settings
2. Add your origin to Allowed Origins:

   https://yourapp.com
   https://myapp.com

Cause: Clock skew between your server and Optare.

Solution:

• Sync your server clock with NTP
• Add a small clockTolerance to token verification:

  jwtVerify(token, JWKS, { clockTolerance: 30 })

Cause: The user exists in one organization but you're querying another.

Solution:

• Check the org_id claim in the token
• Ensure you're querying the correct organization

Cause: Incorrect import.

Solution:

// ✅ Correct
import { OptareClient } from '@optare/optareid-js';
 
// ❌ Wrong
import OptareClient from '@optare/optareid-js';

Cause: Package not installed.

Solution:

npm install @optare/optareid-js @optare/optareid-react

Cause: Missing type definitions or wrong React version.

Solution:

npm install @types/react@18

Checklist:

1. ☐ IdP Entity ID is correct
2. ☐ SSO URL is correct (not logout URL)
3. ☐ Certificate is valid X.509 format
4. ☐ IdP has correct ACS URL configured
5. ☐ Email attribute is mapped correctly

Checklist:

1. ☐ Endpoint returns 200 status
2. ☐ Endpoint is publicly accessible (not localhost)
3. ☐ Correct events are selected
4. ☐ No firewall blocking requests
5. ☐ Check webhook logs in dashboard

Checklist:

1. ☐ CNAME record points to custom.optare.one
2. ☐ DNS has propagated (check with dig)
3. ☐ No CAA records blocking Let's Encrypt
4. ☐ Domain is verified in console

iOS: Check Info.plist has URL scheme:

<key>CFBundleURLSchemes</key>
<array>
    <string>com.yourcompany.yourapp</string>
</array>

Android: Check AndroidManifest.xml has intent filter:

<intent-filter>
    <data android:scheme="com.yourcompany.yourapp" />
</intent-filter>

Android: Ensure minSdkVersion is 23+:

android {
    defaultConfig {
        minSdkVersion 23
    }
}

iOS: Ensure Keychain sharing is enabled in Xcode.