Integrate Google Identity with @nylas/connect

Google Identity Services (GIS) provides OAuth 2.0 authentication for Google accounts. This guide shows you how to use Google as your identity provider with @nylas/connect so your users can sign in with their Google account and connect their email through Nylas.

The Google integration differs slightly from other IdPs because Google Identity Services returns a credential (ID token) directly rather than an access token from an SDK method. You store this credential and pass it to @nylas/connect.

Before you begin

You need a Google Cloud OAuth 2.0 client and a Nylas application configured to work together.

The Google Cloud OAuth client on this page is for Google Sign-In only. The email connection still runs through Nylas Hosted OAuth via your Nylas Google connector — that’s a separate set of Google OAuth credentials. The Nylas Shared Google App — an add-on for Nylas Contract plans — lets you build on a Nylas-verified OAuth application instead of doing the connector-side Google Cloud setup and Google verification yourself.

Configure Nylas Dashboard

Before connecting your identity provider, configure the IDP settings in the Nylas Dashboard:

1. Navigate to your application in the Nylas Dashboard.
2. Go to Hosted Authentication → Identity Providers.
3. Configure the following settings:
   • Allowed Origins: Add the domains where your application will be hosted (e.g., http://localhost:3000, https://yourapp.com). These origins will be allowed to make requests to Nylas with your IDP tokens.
   • Callback URIs: Add the redirect URIs that Nylas will use after authentication (e.g., http://localhost:3000/auth/callback). These must match the redirectUri configured in your NylasConnect instance.

Note

The allowed origins and callback URIs are security measures to prevent unauthorized use of your Nylas application. Include all domains where your application will run, including development, staging, and production environments.

You can access the Identity Provider settings page directly at:

https://dashboard-v3.nylas.com/applications/<YOUR_APP_ID>/hosted-authentication/idp-settings

Configure Google Cloud

1. In the Google Cloud Console, navigate to APIs & Services → Credentials.
2. Create or select an OAuth 2.0 Client ID.
3. Configure the following settings:
   • Application type: Select “Web application”
   • Authorized JavaScript origins: Add your application’s origins (e.g., http://localhost:3000, https://yourapp.com)
   • Authorized redirect URIs: Add your application’s callback URLs (e.g., http://localhost:3000, https://yourapp.com)
4. Save your Client ID for use in your application.

Local development setup

The code examples use http://localhost:3000 as the redirect URI. If your app runs on a different port:

• Update the Authorized JavaScript origins and Authorized redirect URIs in Google Cloud Console
• Update the redirectUri in your @nylas/connect configuration
• Update the Allowed Origins and Callback URIs in your Nylas Dashboard’s Identity Provider settings

For Google OAuth, the origins and redirect URIs must match exactly, including the protocol (http:// for localhost).

Load the Google Identity Services library

Add this script tag to your HTML:

<script src="https://accounts.google.com/gsi/client" async defer></script>

No npm package is required for the vanilla JavaScript integration. The library loads from Google’s CDN.

Implementation

Initialize Google Sign-In and @nylas/connect together. Unlike other IdPs, Google Identity Services provides a credential through a callback rather than an SDK method, so you store it and return it from identityProviderToken:

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

let googleCredential: string | null = null;

function initializeGoogleSignIn() {
  google.accounts.id.initialize({
    client_id: "<GOOGLE_CLIENT_ID>",
    callback: handleGoogleResponse,
  });

  google.accounts.id.renderButton(
    document.getElementById("googleSignInButton"),
    { theme: "outline", size: "large" },
  );
}

function handleGoogleResponse(response: any) {
  googleCredential = response.credential;
  localStorage.setItem("google_credential", googleCredential);
  console.log("Google authentication successful");
}

const nylasConnect = new NylasConnect({
  clientId: "<NYLAS_CLIENT_ID>",
  redirectUri: "http://localhost:3000/auth/callback",
  identityProviderToken: async () => {
    try {
      return localStorage.getItem("google_credential");
    } catch {
      return null;
    }
  },
});

async function connectEmail() {
  try {
    const result = await nylasConnect.connect({
      method: "popup",
      provider: "google",
    });
    console.log("Email connected:", result.grantInfo?.email);
  } catch (error) {
    console.error("Failed to connect email:", error);
  }
}

async function logout() {
  await nylasConnect.logout();
  google.accounts.id.disableAutoSelect();
  localStorage.removeItem("google_credential");
  googleCredential = null;
}

Passing provider: "google" to the connect() method tells Nylas to expect a Google ID token and skips the provider selection screen.

Make API calls

Google Identity Services returns a signed ID token and no user object, so the sub claim has to come out of the token itself. Decode it base64url-safe: JWT payloads use - and _, which atob() rejects outright, so passing the raw segment straight to atob() throws on a subset of tokens.

function decodeSub(token: string): string {
  const part = token.split(".")[1] ?? "";
  const base64 = part
    .replace(/-/g, "+")
    .replace(/_/g, "/")
    .padEnd(Math.ceil(part.length / 4) * 4, "=");
  return JSON.parse(atob(base64)).sub ?? "";
}

async function fetchEmails() {
  const token = localStorage.getItem("google_credential") ?? "";

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

  return await response.json();
}

Two headers do the work. Authorization carries your identity provider’s access token, and X-Nylas-External-User-Id carries the user’s sub claim, which is the same ID your application already stores. Nylas resolves /v3/grants/me to the mailbox linked to that ID, so no grant_id appears in the request.

The same 2 headers work across the Email, Calendar, and Contacts endpoints. Swap /messages for /events or /contacts and nothing else changes. For how the linkage is established, and when to use it instead of storing grant IDs, see use your own user IDs instead of grant IDs.

Use https://api.us.nylas.com for US-hosted applications, or https://api.eu.nylas.com for EU-hosted applications.

Things to know about Google Identity Services

• Token type: Google Identity Services returns an ID token (JWT), not an OAuth access token. This token contains user profile claims like sub, email, and name.
• Token lifetime: Google ID tokens expire after about one hour. The google.accounts.id library does not automatically refresh them. You may need to re-prompt the user or use the google.accounts.id.prompt() method.
• One Tap sign-in: You can enable Google One Tap for a smoother sign-in experience by calling google.accounts.id.prompt() after initialization.
• Credential storage: The example above stores the credential in localStorage. For production apps, consider your security requirements around client-side token storage.

What’s next

• Google + @nylas/connect with React for React-based implementations using @react-oauth/google
• Session management for monitoring connection state
• Error handling for handling authentication failures
• @nylas/connect overview for standalone OAuth without an IdP