Authentication issues are the most common source of support requests for Nylas integrations. This page covers the errors developers encounter most often and how to resolve them.
Looking for grant management issues? See Manage grants for guidance on listing, refreshing, and deleting grants.
401 Unauthorized
Section titled “401 Unauthorized”A 401 response means the request could not be authenticated. The most common causes:
Expired or invalid API key Your API key may have been rotated, or you may be using a key from a different Nylas application. Verify the key in the Nylas Dashboard under API Keys.
Wrong grant_id
Check that the grant_id you’re passing belongs to the correct Nylas application and environment (production vs. staging). Grant IDs are not portable across applications.
Using an access token after it expired If you’re using Hosted OAuth with access token, access tokens expire and require a refresh. If your refresh token has also expired (or was revoked), the user needs to re-authenticate. See Manage grants for how to detect and handle token expiry.
Data residency mismatch
If your Nylas application is provisioned in the EU region, use api.eu.nylas.com instead of api.us.nylas.com. Using the wrong regional endpoint always returns a 401.
403 Forbidden
Section titled “403 Forbidden”A 403 means the request was authenticated but the grant doesn’t have permission to perform the action. This almost always means missing or insufficient OAuth scopes.
Microsoft: missing Mail.ReadWrite for sending
A common gotcha — Microsoft requires Mail.ReadWrite on top of Mail.Send to create and send messages via the Nylas API. Add Mail.ReadWrite to your connector’s scope list, then have the affected user re-authenticate to issue a new grant with the updated scopes.
Google: restricted scopes not approved
If your Google OAuth app hasn’t completed verification for a restricted scope (such as gmail.modify), users outside your test group will get a 403 when that scope is exercised. Either use a less-restricted scope or complete the Google verification process.
Scopes were changed after the grant was created Adding new scopes to a connector doesn’t automatically update existing grants. Users need to go through the auth flow again to issue a grant with the new scopes.
grant.not_found
Section titled “grant.not_found”This error means Nylas can’t find the grant for the grant_id you provided.
The grant was deleted Grants can be deleted manually (via the Dashboard or API), or automatically if the underlying provider token is revoked. Check the Nylas Dashboard to confirm the grant still exists under Grants.
Wrong environment
A grant created in your staging application won’t exist in your production application. Make sure the grant_id and API key belong to the same Nylas application.
Data residency mismatch
Grants are tied to the region where they were created. A grant created in the EU region (api.eu.nylas.com) won’t be found if you query the US region, and vice versa.
The grant was revoked by the provider Google and Microsoft can revoke access if the user removes your app from their account, if your OAuth app fails verification, or if an admin in their organization revokes permissions. When this happens, the grant becomes invalid and the user must re-authenticate.
Google: double authorization redirect
Section titled “Google: double authorization redirect”When a user authenticates with Google through Nylas Hosted OAuth, they may see the Google consent screen twice. This is expected behavior, not a bug.
The first redirect authorizes your Nylas application with Google. The second redirect is Nylas completing its internal token exchange. Both are part of the standard OAuth flow and are required for Nylas to store and manage the user’s credentials.
If users find this confusing, consider adding a note to your onboarding UI explaining that two Google authorization screens are normal for your integration.
Microsoft: scope requirements differ from Google
Section titled “Microsoft: scope requirements differ from Google”Microsoft and Google use different scope names, and Microsoft enforces a few requirements that catch developers off guard:
| What you need | Microsoft scope | Google scope |
|---|---|---|
| Read email | Mail.Read | gmail.readonly |
| Send email | Mail.Send + Mail.ReadWrite | gmail.send |
| Read calendar | Calendars.Read | https://www.googleapis.com/auth/calendar.readonly |
| Read contacts | Contacts.Read | https://www.googleapis.com/auth/contacts.readonly |
| Maintain access | offline_access | Handled automatically |
offline_access is required for Microsoft connectors if you want Nylas to refresh tokens on the user’s behalf. Without it, the grant will stop working once the initial access token expires.
Admin consent for Microsoft 365 organizations Some Microsoft 365 tenants require admin consent before users can authorize third-party apps. If a user gets an error saying they need admin approval, the tenant admin needs to grant consent for your Azure app. See Microsoft admin consent for details.
IMAP: app password requirements
Section titled “IMAP: app password requirements”Many email providers that use IMAP now block standard password authentication in favor of app-specific passwords. If you’re getting authentication failures with IMAP, check whether the user’s provider requires an app password.
Gmail Google requires an app password for IMAP access when two-factor authentication is enabled. Standard Gmail passwords no longer work for IMAP.
Microsoft personal accounts (Outlook.com) Microsoft has disabled basic authentication for personal Outlook.com accounts. IMAP with app passwords is no longer supported — use Hosted OAuth instead.
Yahoo Mail Yahoo requires an app password for IMAP access. The user’s regular Yahoo password will not work.
iCloud Apple requires an app-specific password for IMAP access. Users generate this from their Apple ID account page.
App passwords are sensitive credentials. Treat them like passwords — never log them, don’t store them in plain text, and handle them with the same care as OAuth tokens.
Grant lifecycle issues
Section titled “Grant lifecycle issues”Expired access tokens Nylas automatically refreshes access tokens for grants created with Hosted OAuth (API key). If you’re using Hosted OAuth with access token, you’re responsible for token refresh. See the access token setup guide for the refresh flow.
Revoked grants after provider account changes If a user changes their password, revokes app access, or an admin removes permissions, the underlying provider token is invalidated. Nylas detects this on the next API call and marks the grant as invalid. You’ll need to prompt the user to re-authenticate. Build a re-auth flow into your application rather than assuming grants are permanent.
invalid_grant from the provider
This error from Google or Microsoft typically means the authorization code was already used (OAuth codes are single-use), the code expired (they’re valid for only a few minutes), or the redirect_uri in your token exchange doesn’t match what was registered. Double-check your callback URI configuration in both your provider app and the Nylas Dashboard.