Quickstart: auth with @nylas/connect

@nylas/connect is a JavaScript library that connects a user’s mailbox to your app. It does 2 things for you: it runs the whole OAuth flow so you don’t build redirect routes or a callback handler, and it lets you keep addressing that user by the ID your app already has.

What does @nylas/connect do?

@nylas/connect is a browser and Node.js library that opens an OAuth popup, completes the PKCE exchange, stores the resulting tokens, and refreshes them in the background. It ships with zero runtime dependencies and handles 4 provider values directly: google, microsoft, imap, and icloud.

Without it, connecting a mailbox means writing an authorization redirect, a callback route, a code-for-token exchange, token storage, and refresh logic. The library replaces those 5 pieces with a single connect() call:

const result = await nylasConnect.connect({ method: "popup" });
console.log(result.grantInfo?.email);

If you omit provider, the user picks their own from the Nylas login screen. Pass it when you already know which mailbox you’re connecting.

Do I still need to store a grant ID?

Not if you connect through an identity provider. Nylas links the grant to the sub claim in your IdP’s JWT, so you keep querying by the user ID your app already stores. You call /v3/grants/me with that ID in a header instead of adding a grant_id column and a lookup to every query path.

That linkage comes from your IdP, so it isn’t available on every setup. The third option below signs its own JSON Web Key Set (JWKS) instead of using a hosted provider. Here’s what each of the 3 setups gets you:

Setup	Skips the OAuth plumbing	Keeps your user IDs
@nylas/connect with Auth0, Clerk, or WorkOS	Yes	Yes
@nylas/connect with a custom JWKS endpoint	Yes	Yes, but you run the JWT infrastructure
@nylas/connect on its own	Yes	No, you store the grant ID

Use an identity provider if you have one. The custom JWKS path works and is documented, but you take on issuing and rotating the signing keys yourself. Running the library on its own is the fastest way to a working prototype, and you can add an IdP later without changing how you call connect().

Before you begin

You need a Nylas account, an application client ID, and an identity provider account. This quickstart uses Auth0, and the pattern is identical for the other 4 options covered in the external IdP guides.

• A Nylas account. Sign up if you don’t have one.
• An identity provider account: Auth0, Clerk, Google Identity, WorkOS, or anything that exposes a JWKS endpoint.
• Node.js and a browser to run the examples.

1. Configure your identity provider

Auth0 needs to know which origin is allowed to request tokens. Create an application in the Auth0 Dashboard, then set the 2 URL fields to your local origin so the popup can return a token to the page that opened it.

1. Set Allowed Callback URLs to http://localhost:3000.
2. Set Allowed Web Origins to http://localhost:3000.
3. Save your Domain and Client ID.

2. Configure your Nylas application

Nylas validates the origin that requests a token and the URI it redirects back to, so both of these 2 values must be registered before the first connect() call succeeds. Add them under Hosted Authentication > Identity Providers in the Dashboard.

• Allowed Origins: http://localhost:3000
• Callback URIs: http://localhost:3000

3. Install the packages

Install the library alongside your IdP’s SDK. @nylas/connect has zero runtime dependencies, so it adds exactly 1 package to your bundle plus whatever your identity provider brings.

npmpnpm

npm install @nylas/connect @auth0/auth0-spa-js

pnpm add @nylas/connect @auth0/auth0-spa-js

For React, install @nylas/react instead and use the useNylasConnect hook, which wraps the same client.

4. Connect a mailbox

The identityProviderToken callback is what ties the 2 systems together. @nylas/connect calls it during the token exchange and sends the JWT to Nylas as idp_claims, which is how the resulting grant gets linked to your user. Return a fresh token each time; most IdP SDKs handle the refresh for you.

TypeScriptJavaScript

import { NylasConnect } from "@nylas/connect";
import { Auth0Client } from "@auth0/auth0-spa-js";

const auth0 = new Auth0Client({
  domain: "<AUTH0_DOMAIN>",
  clientId: "<AUTH0_CLIENT_ID>",
  authorizationParams: {
    redirect_uri: window.location.origin,
  },
});

const nylasConnect = new NylasConnect({
  clientId: "<NYLAS_CLIENT_ID>",
  redirectUri: window.location.origin + "/callback",
  identityProviderToken: async () => {
    return await auth0.getTokenSilently();
  },
});

await auth0.loginWithPopup();

const result = await nylasConnect.connect({ method: "popup" });
console.log("Mailbox connected:", result.grantInfo?.email);

import { NylasConnect } from "@nylas/connect";
import { Auth0Client } from "@auth0/auth0-spa-js";

const auth0 = new Auth0Client({
  domain: "<AUTH0_DOMAIN>",
  clientId: "<AUTH0_CLIENT_ID>",
  authorizationParams: {
    redirect_uri: window.location.origin,
  },
});

const nylasConnect = new NylasConnect({
  clientId: "<NYLAS_CLIENT_ID>",
  redirectUri: window.location.origin + "/callback",
  identityProviderToken: async () => {
    return await auth0.getTokenSilently();
  },
});

await auth0.loginWithPopup();

const result = await nylasConnect.connect({ method: "popup" });
console.log("Mailbox connected:", result.grantInfo?.email);

Replace the 3 placeholder values:

• <AUTH0_DOMAIN>: your Auth0 domain, such as your-app.us.auth0.com
• <AUTH0_CLIENT_ID>: your Auth0 Client ID
• <NYLAS_CLIENT_ID>: your Nylas application’s client ID from the Dashboard

connect() returns a ConnectResult. The email address lives on result.grantInfo?.email, not on the result itself.

5. Call the API with your own user ID

This is the part that saves you a database column. Send your IdP’s access token as the bearer token and your user’s ID in the X-Nylas-External-User-Id header, then address the mailbox as /v3/grants/me. No grant_id appears anywhere in your code.

TypeScriptcURL

const token = await auth0.getTokenSilently();
const user = await auth0.getUser();

const response = await fetch(
  "https://api.us.nylas.com/v3/grants/me/messages?limit=5",
  {
    headers: {
      Authorization: `Bearer ${token}`,
      "X-Nylas-External-User-Id": user?.sub ?? "",
    },
  },
);

const messages = await response.json();
console.log("Latest messages:", messages.data);

curl --request GET \
  --url 'https://api.us.nylas.com/v3/grants/me/messages?limit=5' \
  --header 'Authorization: Bearer <IDP_TOKEN>' \
  --header 'X-Nylas-External-User-Id: <USER_ID>'

The limit parameter caps the response at 5 messages here; the Messages endpoint returns 50 by default and accepts up to 200. The same header works across the Email, Calendar, and Contacts endpoints.

6. Check the connection status

Grants break when a user changes their password or revokes access, so check the status before you rely on a mailbox being reachable. getConnectionStatus() returns 1 of 4 values: connected, expired, invalid, or not_connected.

const status = await nylasConnect.getConnectionStatus();

const session = await nylasConnect.getSession();
if (session?.grantInfo) {
  console.log("Connected as:", session.grantInfo.email);
  console.log("Provider:", session.grantInfo.provider);
}

Treat expired and invalid as recoverable. Re-running connect() preserves the grant ID, object IDs, and sync state, as described in handling expired grants.

What’s next

• Connect with your identity provider covers Auth0, Clerk, Google, WorkOS, and custom JWKS endpoints.
• NylasConnect class reference documents every method and configuration option.
• @nylas/react provides the useNylasConnect hook and a prebuilt button component.
• Choose an authentication method compares this against server-side OAuth, IMAP, and service accounts.
• Email API, Calendar API, and Contacts API are what you call once a mailbox is connected.