Authenticating with Nylas

Nylas creates grants, authenticated connections that give your application access to a user’s email, calendar, and contacts data. Most grants come from an OAuth 2.0 flow. IMAP, iCloud, and Exchange on-premises (EWS) grants use the user’s credentials instead, and bring-your-own authentication creates grants from tokens or credentials you already have. Authentication is part of Nylas Connect, and every API call that reads or writes user data requires a grant_id.

Stuck on sign-in flows or provider setup? Nylas Professional Services includes a go-to-market review of your onboarding and authentication flows, plus collaborative OAuth app setup for Microsoft Entra, Google Cloud, and Zoom.

Separate user authentication from API authorization

OAuth and grants control how users connect their provider accounts to Nylas. The API key on a request controls which Nylas resources the caller can access.

Use Nylas IAM to issue least-privilege API keys for services, workers, and AI agents. An IAM principal combines one resource binding with roles and direct permissions, while the grant continues to represent the connected provider account and its OAuth scopes.

Choose an authentication method

Most server-side integrations 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. If you’re connecting mailboxes from a browser app, @nylas/connect runs the same flow for you and can reuse your existing user IDs.

How each authentication method creates a grant

Hosted auth

Your app

Send the user to Nylas

Redirect to /v3/connect/auth with your client_id and redirect_uri. Add a code_challenge for PKCE.

Optional parameters

• provider: skip the provider picker. Without it, Nylas shows a hosted page where the user chooses.
• login_hint: prefill the user's email address.
• scope: request specific scopes. Without it, Nylas uses the connector's default scopes.
• state: a value Nylas returns to you after sign-in.

User

Signs in

On the provider's consent screen (Google, Microsoft, Yahoo, Zoom), or in a Nylas-hosted form for IMAP, iCloud, and EWS passwords.

code sent to your redirect_uri

Your app

Exchange the code

POST /v3/connect/token with the one-time code, plus the code_verifier for PKCE.

Bring your own auth

Your app

Run your own OAuth flow

Send the user to the provider's consent screen with your own OAuth app.

Provider

Returns tokens

Your app receives the user's refresh token.

Your backend

Send the tokens to Nylas

POST /v3/connect/custom with the refresh token, or IMAP credentials, and your API key.

Agent Account

Your backend

Create the account

POST /v3/connect/custom with provider set to "nylas". Nylas creates the mailbox, with no user sign-in.

Nylas

Existing grant?

Nylas looks for a grant with the same email and connector.

No match

New grant ID

The grant starts as valid. Nylas sends grant.created.

Match found

Same grant ID

Nylas re-authenticates the grant and sends grant.updated with reauthentication_flag: true.

Every method ends with a grant ID that your app uses in API requests. With bring your own auth, your app owns the provider OAuth flow and hands Nylas the tokens. If a grant already exists for the same email and connector, Nylas re-authenticates it and keeps its ID.

Diagram as text

• One of these paths:
  • Hosted auth
    • Your app: Send the user to Nylas: Redirect to /v3/connect/auth with your client_id and redirect_uri. Add a code_challenge for PKCE.
      • Optional parameter provider: skip the provider picker. Without it, Nylas shows a hosted page where the user chooses.
      • Optional parameter login_hint: prefill the user's email address.
      • Optional parameter scope: request specific scopes. Without it, Nylas uses the connector's default scopes.
      • Optional parameter state: a value Nylas returns to you after sign-in.
    • User: Signs in: On the provider's consent screen (Google, Microsoft, Yahoo, Zoom), or in a Nylas-hosted form for IMAP, iCloud, and EWS passwords.
    • Your app: Exchange the code: POST /v3/connect/token with the one-time code, plus the code_verifier for PKCE. (code sent to your redirect_uri)
  • Bring your own auth
    • Your app: Run your own OAuth flow: Send the user to the provider's consent screen with your own OAuth app.
    • Provider: Returns tokens: Your app receives the user's refresh token.
    • Your backend: Send the tokens to Nylas: POST /v3/connect/custom with the refresh token, or IMAP credentials, and your API key.
  • Agent Account
    • Your backend: Create the account: POST /v3/connect/custom with provider set to "nylas". Nylas creates the mailbox, with no user sign-in.
• Nylas: Existing grant?: Nylas looks for a grant with the same email and connector.
• Ends in one of:
  • No match → New grant ID: The grant starts as valid. Nylas sends grant.created.
  • Match found → Same grant ID: Nylas re-authenticates the grant and sends grant.updated with reauthentication_flag: true.

Method	Best for	Token management	Requires redirect UI?	Supported providers
Hosted OAuth (API key)	Most server-side integrations	Nylas manages	Yes	Google, Microsoft, Yahoo (OAuth), plus iCloud, IMAP, and EWS (Nylas-hosted credentials form)
@nylas/connect library	Browser and single-page apps	Library manages	Optional	Google, Microsoft, IMAP, 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, Yahoo, Zoom, IMAP, iCloud, EWS, Agent Accounts
IMAP	Legacy or self-hosted email servers	App passwords	Yes, except with bring your own authentication	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.

Alternative: build on the Nylas verified OAuth application with the Nylas Google Shared App. Your users authenticate through a Nylas-owned, pre-verified Google Cloud project, so you avoid the Google Cloud setup, the OAuth verification, and the CASA assessment entirely. The Google Shared App is available on the annual Pro plan with the Accelerator add-on (available through self-service) and as an add-on for the Enterprise plan (contact the Nylas Sales team to learn more).

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 Nylas from "nylas";

const nylas = new Nylas({
  apiKey: "<NYLAS_API_KEY>",
  apiUri: "<NYLAS_API_URI>",
});

async function createConnector() {
  try {
    const connector = await nylas.connectors.create({
      requestBody: {
        name: "google",
        provider: "google",
        settings: {
          clientId: "<GOOGLE_CLIENT_ID>",
          clientSecret: "<GOOGLE_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 nylas import Client

nylas = Client(
    "<NYLAS_API_KEY>",
    "<NYLAS_API_URI>",
)

connector = nylas.connectors.create(
    request_body={
        "provider": "google",
        "settings": {
            "client_id": "<GOOGLE_CLIENT_ID>",
            "client_secret": "<GOOGLE_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: "<GOOGLE_CLIENT_ID>",
    clientSecret: "<GOOGLE_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(
      "<GOOGLE_CLIENT_ID>",
      "<GOOGLE_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(
        "<GOOGLE_CLIENT_ID>",
        "<GOOGLE_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

Whitelabel Hosted Authentication: replace the Nylas logo on the login page, and register a custom hostname so your own domain appears in the address bar during the OAuth flow.

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.