Authentication APIs

Nylas provides two ways to handle authentication:

• Bring Your Own (BYO) Authentication, which uses the /v3/connect/custom endpoint. In BYO Authentication, you already have refresh tokens for your users, and you just need to create grants for them in Nylas. This endpoint is also used for virtual calendars, IMAP auth, and bulk auth grants.
• Hosted OAuth, where the user completes an OAuth process on the provider, and the provider returns an access token. Depending on your needs, you can use either the user's access token or a Nylas API key to authorize requests after you complete the OAuth flow. See the Authentication documentation for more information.

Hosted authentication with OAuth

OAuth is the modern industry-standard protocol for authorization, and is used by major technology companies like Google, Apple, Microsoft, and others. Nylas supports authentication using the OAuth 2.0 protocol and an additional option to use PKCE for extra security. PKCE is an extension of the OAuth 2.0 protocol that prevents authorization code interception attacks, and makes OAuth 2.0 more secure on mobile devices and client-side applications.

During the OAuth 2.0 authentication flow, the user provides the account that they want to authenticate to Nylas, and they're prompted to allow your application's "scopes" (for example, https://www.googleapis.com/auth/gmail.readonly or https://www.googleapis.com/auth/userinfo.profile). Nylas always returns the fully-qualified Google scopes when you make an Authentication request that references a Google grant. For grants authenticated with other providers, Nylas returns the truncated scopes.

Using Hosted OAuth

To use Hosted OAuth you first need to create a Nylas application in the Nylas Dashboard, then create a connector in that application for each authentication provider. This allows Nylas to get and store each provider's settings, and configure a set of default scopes to apply.

Nylas can detect which provider a user is authenticating with and redirect them to the correct provider's authentication system.

If the user decides to choose different provider settings for an OAuth 2.0 authorization protocol, Nylas allows them to override the default provider connector's settings.

A successful OAuth authorization results in a grant with the scopes that the user allowed.

See Create grants with OAuth 2.0 and PKCE for more information.

Adding the "Sign in with Google" button

Your Google provider auth app must have a "Sign in with Google" button that meets Google's branding guidelines. This applies to the OAuth flow for both personal Gmail (@gmail.com) and Workspace email addresses.

For Hosted authentication, Nylas recommends you do one of the following:

• Configure the OAuth login prompt by setting the prompt parameter with select_provider or detect,select_provider. For more information, see Configure the OAuth login prompt.

  ⚠️ If you add a login_hint that is a personal Gmail or Workspace email address, and you don't configure a prompt during the Hosted auth flow, the user is directed immediately to the Google OAuth page without clicking the "Sign in with Google" button. This can result in delays or failure in verification.

• Use the pre-approved "Sign in with Google" button along with the "Connect your account" button (or other provider login buttons) in your application. For more information, see Google's official Sign in with Google branding guidelines.

For Bring Your Own Authentication, use the pre-approved "Sign in with Google" button along with the "Connect your account" button (or other provider login buttons) in your application.

Learn more about Google verification and security assessment.