You wire up the hosted OAuth flow, click Connect, and the provider’s consent screen throws an error instead of redirecting your user back. The user bounces, no grant comes back, and your logs show a bare error code with no context. OAuth failures almost always trace back to a handful of misconfigurations on the connector or the provider auth app. This page maps each error to its cause and the exact fix.
The flow itself is short: your app sends the user to GET /v3/connect/auth, they sign in at Google or Microsoft, the provider redirects back with a code, and you exchange it at POST /v3/connect/token for a grant. Most errors surface at the consent screen or the token exchange. For the full working flow, see connect user accounts with OAuth.
redirect_uri mismatch
Section titled “redirect_uri mismatch”A redirect URI mismatch means the callback URL in your auth request doesn’t exactly match a URL registered on the provider auth app and your Nylas application. Google returns redirect_uri_mismatch and Microsoft returns AADSTS50011. The match is byte-for-byte: scheme, host, port, path, and trailing slash all have to line up, so https://app.com/callback and https://app.com/callback/ count as two different URIs.
Microsoft states the failure as The reply URL specified in the request does not match the reply URLs configured for the application. Register the callback URI in three places so they agree: the Google or Azure auth app, your Nylas application’s callback URIs, and the redirect_uri you pass to /v3/connect/auth. One stray slash or an http versus https difference is the most common cause of this 1 error. Add callback URIs from the Authentication overview.
App not verified or access denied
Section titled “App not verified or access denied”Google shows an unverified-app warning or returns access_denied when your OAuth app hasn’t passed verification and the user isn’t on the test-user list. During development, add up to 100 test users to the OAuth consent screen and they can connect immediately. Restricted scopes like full Gmail access trigger a security assessment that takes several weeks.
For production access without the warning, complete Google’s review. Request only the scopes your features use, because each restricted scope adds time to the assessment. See the Google verification and security assessment guide for the full process. Microsoft handles this through admin consent instead, covered in the next section, where apps without consent return AADSTS65001 rather than an unverified warning.
Insufficient scopes or 403 after connecting
Section titled “Insufficient scopes or 403 after connecting”A grant connects fine but later calls return 403 when the connector requested fewer scopes than your endpoint needs. Reading Gmail messages needs gmail.readonly, while modifying or deleting them needs gmail.modify. If you created the connector with read-only scopes and your app calls a write endpoint, the provider rejects the request even though the grant is valid.
Fix it by adding the missing scope to the connector and re-authenticating affected users so they approve the wider permission set. Microsoft connectors also need offline_access to receive a refresh token for long-lived sync. The granular scopes reference lists the required and optional scopes for all 6 Nylas APIs per provider, including the exact provider URI strings.
Expired or revoked grant (invalid_grant)
Section titled “Expired or revoked grant (invalid_grant)”A grant goes invalid when the user changes their password, an admin forces a token refresh, or the provider revokes access. The provider returns invalid_grant at the token layer, and Nylas marks the grant expired. Detect it two ways: subscribe a webhook to the grant.expired trigger, which fires within about 10 minutes, and handle 401 responses on every API call.
Recover by re-authenticating, not deleting. Sending the user through the same auth flow refreshes the provider tokens while keeping the same grant ID, object IDs, and sync state. If the grant was invalid for under 72 hours, the missed webhooks are re-sent as a backfill. See handle grant expiry and re-authentication for the detection and recovery pattern.
Quick reference: OAuth errors and fixes
Section titled “Quick reference: OAuth errors and fixes”Most OAuth failures fall into 5 categories, and each maps to a single configuration fix. Use the table to match the symptom your user reports or the error string in your logs to its likely cause, then apply the fix. The provider error strings shown are real codes returned by Google and Microsoft, so you can grep your logs for them directly.
| Symptom | Likely cause | Fix |
|---|---|---|
redirect_uri_mismatch / AADSTS50011 | Callback URI doesn’t match the registered URI exactly | Align the URI across the provider app, Nylas app, and the redirect_uri parameter, including the trailing slash |
Unverified-app warning / access_denied | Google app not verified and user isn’t a test user | Add the user as a test user, or complete Google verification |
AADSTS65001 (consent required) | Microsoft user or admin hasn’t consented to the app | Have an admin grant consent, or enable user consent for verified publishers |
403 on API calls after a successful connect | Connector is missing the scope the endpoint needs | Add the scope to the connector and re-authenticate the user |
invalid_grant / 401 / grant.expired | Token revoked, password changed, or grant expired | Re-authenticate the same grant; never delete and recreate it |
What’s next
Section titled “What’s next”- Connect user accounts with OAuth for the full hosted OAuth flow
- Handle grant expiry and re-authentication for detecting and recovering expired grants
- Granular scopes reference for the exact scope strings per provider and API
- Authentication overview for connectors, callback URIs, and every auth method