Nylas Authentication APIs API

Nylas provides two ways to handle authentication: - **Bring Your Own (BYO) Authentication**, which uses the [`/v3/connect/custom` endpoint](/docs/reference/api/manage-grants/byo_auth/). 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](/docs/v3/calendar/virtual-calendars/), [IMAP auth](/docs/v3/auth/imap/), and [bulk auth grants](/docs/v3/auth/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](/docs/v3/auth/) 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](https://oauth.net/2/) and an additional option to use PKCE for extra security. [PKCE is an extension of the OAuth 2.0 protocol](https://oauth.net/2/pkce/) 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](/docs/reference/api/connectors-integrations/) 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](/docs/reference/api/manage-grants/) with the scopes that the user allowed. See [Create grants with OAuth 2.0 and PKCE](/docs/v3/auth/hosted-oauth-accesstoken/#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](https://developers.google.com/identity/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](/docs/v3/auth/customize-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](https://developers.google.com/identity/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](/docs/provider-guides/google/google-verification-security-assessment-guide/).