Version:
Only show these results:

Auth and Nylas

This page explains the different authentication methods available in Nylas v3, so you can choose the best one for your project. The basic steps to set up authentication are described below, but you should choose the type of authentication for your project first.

Nylas v3 doesn't perform data sync operations to keep your customers' information up-to-date. Instead, the platform retrieves data directly from service providers. For more information, see Changes to authentication in Nylas v3.

ℹ️ Authentication scopes is available for Entry, Core, and Plus plans.

Choose an authentication method

Nylas v3 offers new, simplified, and more secure authentication methods.

💡 Most Nylas applications should use the Hosted OAuth and API key method. This gives your end users the familiar security of OAuth, but removes the need for refresh token management after the initial token exchange. This is the recommended auth method and easiest way to integrate with Nylas.

When you know what type of authentication you want to use, go on to the steps below.

Setting up authentication in v3

Follow these steps to set up authentication in Nylas v3:

  1. If you haven't already, log in to the v3 Dashboard and create a Nylas application.
  2. Generate an API key for your application in the v3 Dashboard.
  3. Create a provider auth app in the provider's console or application.
    • See the detailed instructions for creating a provider auth app in Google and Azure.
  4. Create a connector for the provider you want to authenticate with.
  5. Add your project's callback URIs ("redirect URIs") in the Nylas Dashboard.
  6. Authenticate end users and create grants.

🔍 Nylas creates only one grant per email address in each application. If an end user authenticates with your Nylas application using the email address associated with an existing grant, Nylas re-authenticates the grant instead of creating a new one.

Adding the "Sign in with Google" button

Your Google application 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 in v3, 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 Configuring 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 end user is immediately directed to the Google OAuth screen, 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 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 Custom auth, use the pre-approved "Sign in with Google" button with the “Connect your account” button or other provider login buttons in your application.

Learn more about the Google verification and security assessment process.

Create a connector

📝 Note: You cannot create your own service connectors or change scopes on a Nylas Sandbox application.

A connector stores information about external services you connect to your Nylas application, so you don't need to include them manually in all API calls. You cannot create grants without a connector. You only need to create one connector per provider for each Nylas application, and you can create them either using the v3 Dashboard, or the POST /v3/connectors/ endpoint.

In Nylas v3, you can configure default scopes for each connector. This is a good way to simplify your calls later if you know that all users using a specific connector will require the same scopes. You can also override these default scopes by specifying different scopes when you create a grant.

The example below shows a POST /v3/connectors request, and the result that Nylas returns.

{
  "name": "Staging App 1",
  "provider": "microsoft",
  "settings": {
    "client_id": "abc-def",
    "tenant": "common"
  },
  "scope": [
    "Mail.Read",
    "User.Read",
    "offline_access"
  ]
}   
{
  "name": "Staging App 1",
  "provider": "microsoft",
  "scope": [
    "Mail.Read",
    "User.Read",
    "offline_access"
  ]
}

You can also create a connector using the Nylas SDKs, as in the following examples.

import 'dotenv/config'
import Nylas from 'nylas'

const config = {
  apiKey: process.env.NYLAS_API_KEY,
  apiUri: process.env.NYLAS_API_URI,
}

const nylas = new Nylas(config)

const connector = await nylas.connectors.create({
  requestBody: {
    settings: {
      clientId: process.env.GCP_CLIENT_ID,
      clientSecret: process.env.GCP_CLIENT_SECRET,
    },
    scope: [
      'openid',
      'https://www.googleapis.com/auth/userinfo.email',
      'https://www.googleapis.com/auth/gmail.modify',
      'https://www.googleapis.com/auth/calendar',
      'https://www.googleapis.com/auth/contacts',
    ],
  }
})   
from dotenv import load_dotenv
load_dotenv()

import os
import sys
from nylas import Client

nylas = Client(
    os.environ.get('NYLAS_API_KEY'),
    os.environ.get('NYLAS_API_URI')
)

# Create a connector
connector = nylas.connectors.create(
  request_body={
    "provider": "google",
    "settings": {
      "client_id": os.environ.get('GCP_CLIENT_ID'),
      "client_secret": os.environ.get('GCP_CLIENT_SECRET')
    },
    "scopes": [
      'openid',
      'https://www.googleapis.com/auth/userinfo.email',
      'https://www.googleapis.com/auth/gmail.modify',
      'https://www.googleapis.com/auth/calendar',
      'https://www.googleapis.com/auth/contacts'
    ]
  }
)   
require 'nylas'

nylas = Nylas::Client.new(api_key: "<NYLAS_API_KEY>")

request_body = {
  provider: "google",
  settings: {
    clientId: "<GCP_CLIENT_ID>",
    clientSecret: "<GCP_CLIENT_SECRET>",
  },
  scope: [
    'openid',
    'https://www.googleapis.com/auth/userinfo.email',
    'https://www.googleapis.com/auth/gmail.modify',
    'https://www.googleapis.com/auth/calendar',
    'https://www.googleapis.com/auth/contacts',
  ]
}

nylas.connectors.create(request_body: request_body)   
import com.nylas.NylasClient;
import com.nylas.models.*;
import java.util.ArrayList;
import java.util.List;

public class connector {
  public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {
    NylasClient nylas = new NylasClient.Builder("<NYLAS_API_KEY>").build();
    List<String> scope = new ArrayList<>();

    scope.add("openid");
    scope.add("https://www.googleapis.com/auth/userinfo.email");
    scope.add("https://www.googleapis.com/auth/gmail.modify");
    scope.add("https://www.googleapis.com/auth/calendar");
    scope.add("https://www.googleapis.com/auth/contacts");

    GoogleCreateConnectorSettings settings = new 
    GoogleCreateConnectorSettings("<GCP_CLIENT_ID>", "<GCP_CLIENT_SECRET>","");

    CreateConnectorRequest request = new 
    CreateConnectorRequest.Google(settings, scope);

    nylas.connectors().create(request);
  }
}   
import com.nylas.NylasClient
import com.nylas.models.CreateConnectorRequest
import com.nylas.models.GoogleCreateConnectorSettings

fun main(args: Array<String>) {
  val nylas: NylasClient = NylasClient(apiKey = "NYLAS_API_KEY")

  var scope = listOf(
    "openid",
    "https://www.googleapis.com/auth/userinfo.email",
    "https://www.googleapis.com/auth/gmail.modify",
    "https://www.googleapis.com/auth/calendar",
    "https://www.googleapis.com/auth/contacts")

  val settings : GoogleCreateConnectorSettings = GoogleCreateConnectorSettings("<GCP_CLIENT_ID>", "<GCP_CLIENT_SECRET>", "")
  val request : CreateConnectorRequest = CreateConnectorRequest.Google(settings, scope)

  nylas.connectors().create(request)
}

Creating grants

See the instructions for each authentication method for details on creating grants:

Bulk auth grants and connector credentials

In v3, Nylas also supports Bulk authentication grants (sometimes called "Service Accounts" or "app permissions") which you can use to do bulk re-authentication and other backend tasks.

Referencing grants in API requests

You can locate grants authenticated to your application in any of the following ways:

  • Using the grant_id. This is the simplest method, and the format that you see throughout the docs.

  • Using the /me/ construction and an access token in your API call. Nylas uses the access token to find the grant it's associated with, and uses the grant_id internally.

    curl --request GET \
      --url https://api.us.nylas.com/v3/grants/me/messages/ \
      --header 'Accept: application/json, application/gzip' \
      --header 'Authorization: Bearer <NYLAS_ACCESS_TOKEN>' \
      --header 'Content-Type: application/json'

  • Using an authenticated email address in place of the grant ID.

    curl --request GET \
      --url https://api.us.nylas.com/v3/grants/nyla@example.com/messages/ \
      --header 'Accept: application/json, application/gzip' \
      --header 'Authorization: Bearer <NYLAS_API_KEY>' \
      --header 'Content-Type: application/json'

Terms

  • Provider: The email or calendar provider that you want to connect to the Nylas platform (for example, Google or Microsoft). This can also be an IMAP provider.
  • Provider auth application: Both Microsoft and Google require that you use a verified application that runs on their platform in order to connect accounts.
  • Connector: A connector stores information in your Nylas application that allows it to connect to another service (for example, an authentication provider such as Microsoft or Google, or a conferencing service, like Zoom, Meet, or Microsoft Teams).
  • Grant: In v3, the term "grant" replaces the concept of a connected account. The Grant is a record of the user account, its provider, and the approved scopes (with other details) that Nylas was given access to when the user authenticated. For example, when you authenticate with Google, Nylas returns a grant ID that is linked to the Google email address.
  • Scopes: Scopes define what level of access is being granted, and to what data objects on each provider. You set the scopes your project needs on your provider auth application. You can also set default scopes on each connector, and explicit scopes on each grant.

What's next?

Now that you have authentication set up and a grant to work with, you can browse the following documentation to learn more.