Troubleshooting common authentication failures
Most auth issues fall into a small set of operational categories. Work through these checks before treating a provider flow as an SDK defect.
Redirect mismatches
Verify the exact callback URI, including scheme, host, and path, matches both your application configuration and the provider dashboard registration. Mobile targets often fail because a custom URI scheme changed between debug and release builds.
Token refresh failures
If refresh fails repeatedly, inspect the provider response before retrying. `invalid_grant`, revoked sessions, or tenant configuration changes usually require an interactive login instead of another refresh attempt.
- Confirm system clocks are synchronized on the target device.
- Check whether offline access or refresh-token issuance is enabled for the provider app.
- Log provider-specific error codes alongside the normalized SDK exception.
Provider rollout issues
Rollout failures usually come from partial configuration: one environment updated, another left behind. Promote provider configuration through the same deployment pipeline you use for the application so tenant and callback values move together.
Fastest validation path
Test install, login, refresh, and logout in staging with the exact provider settings that production will receive. If one of those four steps breaks, stop the rollout until configuration is corrected.