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.

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

Choose an authentication method

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.

• If your project is a mobile app or runs in-browser, use Hosted OAuth with Access token and PKCE. This method lets you securely authenticate front-end apps without the need to ship your API key with your code.
• If you want the security of OAuth and are happy working with access and refresh tokens, use Hosted OAuth with Access token (with or without PKCE) even for a server-based project.
• If you already have credentials for your end users, use Custom authentication (formerly known as “Native authentication”).
• If you’re using IMAP, see the IMAP authentication guide.
• If you’re using Virtual Calendars, see the Virtual Calendar guide.

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

You can’t 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.

RequestResponse (JSON)

{
  "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.

Node.js SDKPython SDKRuby SDKJava SDKKotlin SDK

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:

• (Recommended) Hosted authentication with OAuth and API key
• Hosted authentication with OAuth and Access token
• Custom authentication (previously called “Native authentication”)
• IMAP authentication
• Virtual Calendars

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/[email protected]/messages/ \
    --header 'Accept: application/json, application/gzip' \
    --header 'Authorization: Bearer <NYLAS_API_KEY>' \
    --header 'Content-Type: application/json'