Authenticating with Nylas

Copy as MarkdownCurl Markdown

Open in

Nylas uses OAuth 2.0 to create grants — authenticated connections that give your application access to a user’s email, calendar, and contacts data. Every API call that reads or writes user data requires a grant_id.

Choose an authentication method

Most applications should use Hosted OAuth with API key. Nylas handles token refresh after the initial exchange, so you only ever use your API key and the user’s grant_id.

Method	Best for	Token management	Requires redirect UI?	Supported providers
Hosted OAuth (API key)	Most server-side integrations	Nylas manages	Yes	Google, Microsoft, Yahoo, iCloud
Hosted OAuth (access token + PKCE)	SPAs and mobile apps	You manage refresh	Yes	Google, Microsoft
Bring your own authentication	Teams with an existing OAuth flow	You manage entirely	No	Google, Microsoft
IMAP	Legacy or self-hosted email servers	App passwords	No	Any IMAP server
Service account	Server-to-server, no user interaction	Nylas manages	No	Google Workspace

Before you begin

Before setting up authentication, you need:

• A Nylas account — sign up if you don’t have one yet
• A Nylas application and API key — see Create a Nylas application and Get your API key
• A provider auth app for Google or Microsoft integrations (see Create provider auth apps)
• At least one connector configured in your Nylas application (see Create connectors)

Set up authentication

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

Create provider auth apps

If you plan to connect Google or Microsoft accounts, you need a provider auth app. You can use it with internal accounts right away for development and testing — the provider review only matters before you go live.

We recommend maintaining separate provider auth apps per environment so you can adjust scopes and settings in development without affecting production users. The review process can take several weeks, so plan this into your timeline.

Google application review

Request only the most restrictive scopes you need. If you request any of Google’s restricted scopes, Google requires a full security assessment — this can significantly extend your verification timeline.

See the Google verification and security assessment guide for details.

Create connectors

You can’t create connectors or change scopes on a Nylas Sandbox application. Sandbox applications include a limited set of pre-configured connectors for testing.

Connectors store your provider app credentials so you don’t need to include them in every API call. You can’t create grants without at least one connector.

Create connectors from the Nylas Dashboard under Connectors, or with the Create Connector API endpoint.

RequestResponse (JSON)Node.jsPythonRubyKotlinJava

{
  "name": "Staging App 1",
  "provider": "microsoft",
  "settings": {
    "client_id": "<PROVIDER_CLIENT_ID>",
    "client_secret": "<PROVIDER_CLIENT_SECRET>",
    "tenant": "common"
  },
  "scope": ["Mail.Read", "User.Read", "offline_access"]
}

{
  "name": "Staging App 1",
  "provider": "microsoft",
  "scope": ["Mail.Read", "User.Read", "offline_access"]
}

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

Each connector supports multiple credentials, letting you use different provider auth apps with a single connector. You can also set default scopes per connector and override them when creating individual grants.

For bulk setup and multi-app configurations, see Bulk authentication grants and Using multiple provider applications.

Add callback URIs to your Nylas application

Callback URIs are where Nylas redirects users after they complete authentication.

1. Log in to the Nylas Dashboard.
2. On your application’s page, click Hosted Authentication > Callback URIs in the left navigation.
3. Click Add a callback URI.
4. Select the platform and enter a URL.
5. Click Add callback URI.

Customize Hosted Authentication branding

Customize Hosted Authentication branding: add your logo to the login page, set up a custom domain (CNAME) for your authentication flow, and more.

Handle expired grants

Grants can expire when users change passwords, revoke access, or when provider tokens are invalidated. Expired grants are recoverable through re-authentication, which preserves the grant ID, object IDs, and sync state. See Handling expired grants for best practices on detection and recovery.