Nylas Connect library overview

Nylas maintains the @nylas/connect library, a JavaScript/TypeScript library that you can use to add a simple authentication mechanism to your project. It automatically manages OAuth flows, token storage, and grant creation across multiple providers, meaning you can get to making API requests more quickly.

The recommended way to use Nylas Connect is with external identity providers (IDPs), allowing you to integrate email functionality with your existing authentication system.

What are external identity providers?

External identity providers (IDPs) are authentication services that manage user identities and credentials for your application. Instead of building your own authentication system, you use a trusted provider to handle user sign-in, security, and identity management.

Popular identity providers include:

• Auth0 - Enterprise authentication platform
• Clerk - Modern authentication with prebuilt UI components
• Google Identity - OAuth 2.0 authentication for Google accounts
• WorkOS - Enterprise SSO and directory sync
• Custom IDPs - Any identity provider with JWKS (JSON Web Key Set) endpoints

Why use an external IDP with Nylas Connect?

Using an external IDP with Nylas Connect provides several benefits:

• Unified authentication: Users sign in once with your IDP, then connect their email accounts seamlessly
• Simplified API calls: Make Nylas API requests using your IDP tokens instead of managing separate API keys
• Enhanced security: Leverage your IDP’s security features, compliance, and best practices
• Better user experience: Users don’t need to authenticate separately for email functionality

Get Started with External IDPs

Ready to integrate? Follow the External Identity Provider guide for step-by-step instructions with Auth0, Clerk, Google, WorkOS, or any custom IDP with JWKS support.

Standalone OAuth (Alternative)

If you don’t have an existing authentication system or are building a simple prototype, you can use Nylas Connect for direct OAuth flows without an external IDP. The sections below show how to implement standalone OAuth authentication.

Before you begin

For external IDP integration (Recommended)

If you’re using an external identity provider, you need:

• Your identity provider account (Auth0, Clerk, Google, WorkOS, etc.)
• Your Nylas application’s client ID
• Allowed origins and callback URIs configured in the Nylas Dashboard IDP settings
• The @nylas/connect package installed

See the External Identity Provider guide for detailed setup instructions.

For standalone OAuth

If you’re using standalone OAuth (without an external IDP), you need:

• A working OAuth redirect URI

• Your Nylas application’s client ID

• The @nylas/connect package installed in your environment

  npmpnpm

  npm install @nylas/connect

  pnpm add @nylas/connect

Configuration settings

With external identity provider (Recommended)

When using an external IDP, configure NylasConnect with the identityProviderToken callback:

import { NylasConnect } from "@nylas/connect";

const nylasConnect = new NylasConnect({
  clientId: "<NYLAS_CLIENT_ID>",
  redirectUri: "http://localhost:3000/auth/callback",
  apiUrl: "https://api.us.nylas.com", // or https://api.eu.nylas.com
  // Provide your IDP's access token
  identityProviderToken: async () => {
    // Return your IDP token (from Auth0, Clerk, Google, etc.)
    return await getYourIdpToken();
  },
  environment: "production",
  persistTokens: true
});

Using Custom IDPs with JWKS

Nylas Connect works with any identity provider that exposes a JWKS (JSON Web Key Set) endpoint. This includes custom authentication systems, enterprise IDPs, and open-source solutions like Keycloak or Ory. Simply configure your IDP’s JWKS endpoint in the Nylas Dashboard and provide tokens via the identityProviderToken callback.

Standalone OAuth configuration

The Nylas Connect library automatically detects the following environment variables:

# Client ID (required)
NYLAS_CLIENT_ID=your_client_id
# or for Vite
VITE_NYLAS_CLIENT_ID=your_client_id

# Redirect URI (required)
NYLAS_REDIRECT_URI=http://localhost:3000/auth/callback
# or for Vite
VITE_NYLAS_REDIRECT_URI=http://localhost:3000/auth/callback

You can also configure manually:

const nylasConnect = new NylasConnect({
  clientId: "<NYLAS_CLIENT_ID>",
  redirectUri: "http://localhost:3000/auth/callback",
  apiUrl: "https://api.us.nylas.com", // or https://api.eu.nylas.com
  defaultScopes: [], // If not provided, we default to your connector scopes
  environment: "development",         // "development" | "staging" | "production"
  persistTokens: true,                // Store tokens in localStorage
  debug: true,                        // Enable debug logging
  logLevel: "info"                    // "error" | "warn" | "info" | "debug" | "off"
});

Provider-specific configuration settings

Every provider requests different information as part of its OAuth flow. You’ll need to configure the information you pass for each provider your project supports.

GoogleMicrosoftIMAP

const result = await nylasConnect.connect({
  method: "popup",
  provider: "google",
  scopes: [
    "https://www.googleapis.com/auth/gmail.readonly",
    "https://www.googleapis.com/auth/calendar.readonly"
  ],
  loginHint: "user@example.com" // Pre-fill email address
});

const result = await nylasConnect.connect({
  method: "popup",
  provider: "microsoft",
  loginHint: "user@company.com"
});

const result = await nylasConnect.connect({
  method: "popup",
  provider: "imap"
  // User will be prompted for IMAP settings
});

Set up basic authentication (Standalone OAuth)

Caution

The following sections describe standalone OAuth implementation without an external identity provider. For most applications, we recommend using an external IDP instead.

The Connect library supports two ways to set up basic authentication: using a pop-up flow, or an inline flow.

Set up basic authentication using pop-up flow

When you use the pop-up flow, your project opens the OAuth prompt in a pop-up window and the user authenticates without leaving your application. This method works well if you’re creating a single-page application (SPA).

import { NylasConnect } from "@nylas/connect";

// Initialize with environment variables (recommended)
const nylasConnect = new NylasConnect();

try {
  // Start OAuth flow in popup window
  const result = await nylasConnect.connect({ method: "popup" });

  // Extract grant information
  const { grantId, grantInfo } = result;
  console.log(`Connected ${grantInfo?.email} via ${grantInfo?.provider}`);

  // Store grantId for future API calls
  localStorage.setItem('nylasGrantId', grantId);
} catch (error) {
  console.error('Authentication failed:', error);
}

Set up basic authentication using inline flow

When you use the inline flow, your project redirects the user’s browser to the OAuth provider where they authenticate. After the authentication process is complete, the provider returns the user to your project. We recommend this method for mobile browsers or other scenarios where the user’s browser might not support pop-ups.

// For redirect-based flow
const url = await nylasConnect.connect({ method: "inline" });
window.location.href = url;
// User will be redirected to OAuth provider

Handle OAuth callback

Now that you have basic authentication set up, you need to make sure your project can handle the OAuth callback.

// On your callback page (e.g., /auth/callback)
try {
  const result = await nylasConnect.callback();
  const { grantId, email } = result;
  console.log(`Successfully authenticated: ${email}`);
} catch (error) {
  console.error('Callback handling failed:', error);
}

Set up error handling

You can set up error handling for your authentication flow using either the try-catch method or state change events that Nylas Connect generates.

Try-catchState change events

try {
  const result = await nylasConnect.connect({ method: "popup" });
  console.log('Connection successful:', result);
} catch (error) {
  if (error.name === 'PopupError') {
    console.error('Popup was blocked or closed');
  } else if (error.name === 'ConfigError') {
    console.error('Configuration error:', error.message);
  } else if (error.name === 'OAuthError') {
    console.error('OAuth error:', error.message);
  } else {
    console.error('Unexpected error:', error);
  }
}

nylasConnect.onConnectStateChange((event, session, data) => {
  switch (event) {
    case 'CONNECT_SUCCESS':
      console.log('Successfully connected:', session?.grantInfo?.email);
      break;
    case 'CONNECT_ERROR':
      console.error('Connection failed:', data?.error);
      break;
    case 'CONNECT_CANCELLED':
      console.log('User cancelled authentication');
      break;
    case 'CONNECT_STARTED':
      console.log('Authentication started');
      break;
  }
});

Manage authenticated grants

Nylas Connect makes calls to the Nylas APIs to manage grants’ connection status in your project.

Check grant connection status

Your project should check users’ grant connection status intermittently to ensure they’re still authenticated.

// Check connection status
const status = await nylasConnect.getConnectionStatus();
console.log(`Connection status: ${status}`); // "connected" | "expired" | "invalid" | "not_connected"

// Get session information (includes grant info)
const session = await nylasConnect.getSession();
if (session?.grantInfo) {
  console.log(`Connected as: ${session.grantInfo.email}`);
  console.log(`Provider: ${session.grantInfo.provider}`);
  console.log(`Grant ID: ${session.grantId}`);
}

Log a user out

When a user chooses to log out of your project, you need to call nylasConnect.logout(). If you don’t pass a grant ID in your call, Nylas Connect logs the current user out.

// Logout current user
await nylasConnect.logout();

// Logout specific grant
await nylasConnect.logout('specific-grant-id');

Set up single sign-on support

You can add support for single sign-on (SSO) to your project by including the following code.

// Check for existing session on app load
const session = await nylasConnect.getSession();

if (session) {
  // User is already authenticated, proceed to app
  initializeApp(session.grantInfo);
} else {
  // Show login button
  showLoginButton();
}

Set up support for multiple accounts

If you want to allow your users to authenticate multiple accounts to your project, you can configure Nylas Connect to get information about all of their authenticated grants.

// Connect additional accounts
const secondAccount = await nylasConnect.connect({
  method: "popup",
  provider: "microsoft"
});

// Manage multiple grants
const allSessions = await Promise.all([
  nylasConnect.getSession('grant-1'),
  nylasConnect.getSession('grant-2')
]);

// Access grant information from each session
allSessions.forEach((session) => {
  if (session?.grantInfo) {
    console.log(`Account: ${session.grantInfo.email}`);
  }
});