NylasConnect class overview

The NylasConnect class is the core of the Nylas Connect library. It provides methods for OAuth authentication, token management, and grant creation and management. The primary use case for NylasConnect is integrating with external identity providers (IDPs) like Auth0, Clerk, Google Identity, and WorkOS, allowing you to link your users’ existing identities with their email accounts.

Basic configuration

When using NylasConnect with an external identity provider, configure it with the identityProviderToken callback:

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

const nylasConnect = new NylasConnect({
  clientId: process.env.NYLAS_CLIENT_ID!,
  redirectUri: process.env.NYLAS_REDIRECT_URI!,
  apiUrl: process.env.NYLAS_API_URL || "https://api.us.nylas.com",
  // Provide your IDP token for authenticated API calls
  identityProviderToken: async () => {
    return await getYourIdpToken();
  },
  environment: "production",
  persistTokens: true,
  debug: false,
  logLevel: "error",
});

// Set up authentication state monitoring
nylasConnect.onConnectStateChange((event, session, data) => {
  console.log("Auth state changed:", event);

  switch (event) {
    case "SIGNED_IN":
      // Handle successful connection
      console.log("Connected:", session?.grantInfo?.email);
      break;
    case "SIGNED_OUT":
      // Handle disconnection
      console.log("Disconnected");
      break;
    case "CONNECT_ERROR":
      // Handle authentication errors
      console.error("Auth error:", data?.error);
      break;
  }
});

`ConnectConfig`

The NylasConnect constructor accepts a ConnectConfig object with the following options.

Property

Type

Default

Integration patterns

External identity provider integration (Recommended)

The recommended way to use NylasConnect is with an external identity provider. This pattern allows you to:

Unified authentication: Users authenticate once with your IDP (Auth0, Clerk, Google, WorkOS, etc.)
Seamless email access: Link their email accounts to their existing identity
Simplified API calls: Use IDP tokens instead of managing separate API keys
Enhanced security: Leverage your IDP’s security features and compliance

Get started: Follow the External Identity Provider guide for implementation steps with your chosen provider.

Standalone OAuth integration

You can also use NylasConnect for direct OAuth flows without an external IDP. This is suitable for:

Simple applications that only need email access
Prototypes and proof-of-concepts
Scenarios where you don’t have an existing authentication system

For standalone usage, see the Nylas Connect overview for basic implementation.

Methods

The NylasConnect class includes the following methods. Click on any method name to view its detailed documentation.

Authentication methods

Method

Type

Default

connect()

(options: ConnectOptions = {}): Promise<ConnectResult>

connect()

(options: ConnectOptions = {}): Promise<ConnectResult>

—

getAuthUrl()

getAuthUrl(options: ConnectOptions = {}): Promise<{ url: string; state: string; scopes: string[]; }>

getAuthUrl()

getAuthUrl(options: ConnectOptions = {}): Promise<{ url: string; state: string; scopes: string[]; }>

—

onConnectStateChange()

(callback: ConnectStateChangeCallback) => () => void

onConnectStateChange()

(callback: ConnectStateChangeCallback) => () => void

—

Callback methods

Method

Type

Default

callback()

(url?: string): Promise<ConnectResult>

callback()

(url?: string): Promise<ConnectResult>

—

handleRedirectCallback()

(url?: string): Promise<ConnectResult>

handleRedirectCallback()

(url?: string): Promise<ConnectResult>

—

Grant management methods

Method

Type

Default

getConnectionStatus()

(grantId?: string): Promise<ConnectionStatus>

getConnectionStatus()

(grantId?: string): Promise<ConnectionStatus>

—

getSession()

(grantId?: string): Promise<SessionData | null>

getSession()

(grantId?: string): Promise<SessionData | null>

—

logout()

(grantId?: string): Promise<void>

logout()

(grantId?: string): Promise<void>

—

Utility methods

Method

Type

Default

setLogLevel()

(level: LogLevel | "off"): void

setLogLevel()

(level: LogLevel | "off"): void

—

Property types

`ConnectError`

ConnectError extends the standard Error interface and adds fields for better error handling.

Property	Type	Description
`code`	string	An error code for programmatic error handling.
`description`	string?	A human-readable description of the error.
`docsUrl`	string?	A link to relevant documentation.
`fix`	string?	A suggested solution for resolving the error.
`originalError`	Error?	The original error, if the `ConnectError` wraps another error.

`Environment`


Name	`Environment`
Description	Your project’s deployment environment.
Enum	`development \| staging \| production`

`ProviderScopes`

Default scope settings for different providers.

type ProviderScopes = {
  google?: GoogleScope[];
  microsoft?: MicrosoftScope[];
  yahoo?: YahooScope[];
  imap?: never;       // IMAP doesn't support scopes
  icloud?: string[];  // iCloud uses custom scopes
};

const nylasConnect = new NylasConnect({
  clientId: "<NYLAS_CLIENT_ID>",
  redirectUri: "https://yourapp.com/callback",
  defaultScopes: {
    google: ["https://www.googleapis.com/auth/gmail.readonly"],
    microsoft: ["https://graph.microsoft.com/Mail.Read"],
  },
});