Authenticating with Nylas

Nylas offers a few different authentication methods, so you can choose the best one for your project. This page explains each authentication type and how to set up the auth flow for your project.

Choose an authentication method

Most Nylas applications should use the Hosted OAuth and API key method. This gives your users the familiar security of OAuth, but removes the need for refresh token management after the initial token exchange.

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 an Access token (with or without PKCE) even for a server-based project.
If you already have credentials for your users, use Bring Your Own 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.

Set up authentication

If you haven’t already, log in to the Nylas Dashboard and create a Nylas application.
Get your application’s API key.
Create auth apps for the providers you plan to integrate with.
Create connectors for your provider auth apps. Nylas supports Google, Microsoft, IMAP, Exchange on-premises, iCloud, Yahoo, and Zoom Meetings.
Add your project’s callback URIs to your Nylas application.
Authenticate your users and create grants for them.

Create provider auth apps

If you expect to connect to Google or Microsoft accounts, you’ll need to create a provider auth app to connect to their servers.

You can use provider auth apps with internal company accounts for development and testing with no extra steps. You’ll need to get it reviewed by the provider, however, before you can “go live” with your project. We recommend you maintain a provider auth app for each of your environments so you can make changes in your development and testing environments without affecting your production users.

Creating a provider auth app is straightforward, and you can create one (or several) quickly so you can start developing. The provider review can take several weeks, however, and depends entirely on the provider’s review process and which scope your project requests. Be sure to plan this into your development timeline!

Google application review

You might need to take extra steps to comply with Google’s OAuth 2.0 policies and complete their verification process before you can publish your Google auth app.

Be sure you’re requesting only the most restrictive scopes that you need for your project. If you request any of Google’s restricted scopes, Google requires your application to complete a security assessment. This could extend your verification timeline significantly or cause Google to fail your review.

For more information, see our Google verification and security assessment guide.

Create connectors

You can’t create your own connectors or change scopes on a Nylas Sandbox application. Sandbox applications include a limited set of pre-configured connectors you can use to test your authentication flow.

Connectors store information about the external services you connect to your Nylas application, so you don’t need to include them manually in all API calls. You can’t create grants for your users without at least one connector.

You only need one connector per provider for each Nylas application, and you can create them by either logging in to the Nylas Dashboard and selecting Connectors from the left navigation, or making a Create Connector request.

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

// Nylas configuration
const NylasConfig = {
  apiKey: process.env.NYLAS_API_KEY,
  apiUri: process.env.NYLAS_API_URI,
}

const nylas = new Nylas(NylasConfig)

const identifier = process.env.NYLAS_GRANT_ID

async function createConnector() {
  try {
    const connector = await nylas.connectors.create({
      requestBody: {
        name: 'google',
        provider: 'google',
        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',
        ],
      },
    });

    console.log('Connector created:', connector)
  } catch (error) {
    console.error('Error creating connector:', error)
  }
}

createConnector()

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.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)
}

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);
  }
}

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.

Bulk auth grants and connector credentials

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.