Skip to content

Create a Google auth app

This page explains how to create and configure a Google Cloud Platform (GCP) application to use with your Nylas project.

Before you begin

Before you create your GCP application, you must plan a couple fundamental parts of your project:

Choose authentication method

First, you must decide which authentication method works for you: Hosted OAuth or Custom authentication.

Hosted OAuth is the fastest way to get started. If you’re not interested in customizing your application, or you just want to test with a few end users, Nylas recommends you use Hosted OAuth.

Custom authentication allows you to customize your application’s auth process. This means your end users will see your company name instead of “Nylas” on the OAuth screen. If you choose to use Custom auth, you must have an existing v3 Nylas application and a callback URI.

Choose external or internal application

You must also decide if you want to make your GCP application available to anyone (external) or only end users that are part of your organization (internal).

If your GCP app will need to go through Google’s security verification process, create an external application. This option allows end users who aren’t from your organization to authenticate with your application. When external users authenticate with your application, they are shown an “Unverified application” warning.

Unverified external GCP applications are limited to 100 authenticated accounts. To raise this limit, you must complete Google’s security verification process. For more information, see Google’s official Unverified apps documentation.

If you’re creating a development or production app for internal use only, Nylas recommends you create an internal application. Only end users who have accounts within your organization (for example, any end user with an @nylas.com email address) will be able to access the application.

Internal GCP applications allow you to skip Google’s verification and security review process. If anyone outside your organization needs to authenticate with your app, you’ll need to go through Google’s security review.

Create Google provider auth app

Follow these steps to create a Google provider auth app:

  1. Go to the Google Cloud Console Create Project page.
  2. Give your project a name.
  3. Select your project’s Organization and Location.

Google Cloud Platform "Create Project" page. The form is filled out with demo information.

It might take several minutes for Google to create your project. When the process is finished, Google redirects you to the dashboard and displays a Create Project notification.

A Google Cloud Platform "Create Project" notification.

Enable required APIs

You must enable certain APIs for your Google provider auth app to work with Nylas v3.

  1. From the Google Cloud Platform dashboard, select APIs and services.
  2. Click Enable APIs and services. The Google Cloud Platform Console showing the "APIs and services" page. A mostly-empty graph of traffic is displayed.
  3. Search for and enable the following APIs:
    • Gmail API: Required to read and send email messages. Also required for the Threads, Drafts, Folders, and Files endpoints.
    • People API: Required to use the Contacts endpoints.
    • Admin SDK API: Optional. Grants access to room information for calendar events.

Google authentication scopes

Before you can publish your GCP project, you might have to take extra steps to comply with Google’s OAuth 2.0 policies and complete their verification process. Be sure to request the most restrictive scopes that you need for your GCP application. If you request any of Google’s restricted scopes, Google will require your application to complete a security assessment. This could extend your verification timeline significantly, or cause Google to fail your review.

For more information, see the Google verification and security assessment guide.

The table below lists the available Google auth scopes.

Google Scope URIDescription
https://www.googleapis.com/auth/userinfo.emailRequired Google scope.
https://www.googleapis.com/auth/userinfo.profileRequired Google scope.
openidRequired Google scope.
https://www.googleapis.com/auth/gmail.modifyRead, compose, and send email messages from a Gmail account.
https://www.googleapis.com/auth/gmail.readonlyView email messages.
https://www.googleapis.com/auth/gmail.labelsView and edit Gmail labels.
https://www.googleapis.com/auth/gmail.composeCreate drafts and send email messages.
https://www.googleapis.com/auth/gmail.sendSend email messages.
https://www.googleapis.com/auth/calendarView, create, edit, and delete calendars and events.
https://www.googleapis.com/auth/calendar.readonlyView calendars and events.
https://www.googleapis.com/auth/calendar.eventsView and edit events on all calendars.
https://www.googleapis.com/auth/calendar.events.readonlyView events on all calendars.

For more information about scopes in Nylas v3, see the Scopes documentation.

Automatically include previously granted scopes

Nylas includes Google’s include_granted_scopes feature flag when authenticating with Google OAuth 2.0. This feature flag tells Google to include any scopes that the end user already approved on the specific GCP app (assuming the scopes are still valid). This simplifies the auth process for your end users, because they’re no longer required to re-select the scopes they already approved when they authenticate again.

Configure Google OAuth page

You can configure the OAuth page for both internal and external GCP applications. This is the page that your end users are directed to when they authenticate with your Nylas application.

Configure internal OAuth page

Follow these steps to configure an OAuth page for internal users:

  1. From the Google Cloud Platform dashboard, select OAuth consent screen.
  2. Choose the Internal user type and click Create.
  3. Fill out the required OAuth consent information and enter nylas.com as an Authorized domain.
  4. Click Save and continue.
  5. Select Add or remove scopes, and add the .../auth/userinfo.email, .../auth/userinfo.profile, and openid scopes.
  6. Select the scopes needed for your application.
  7. Review the Summary and ensure the information is correct.

Configure external OAuth page

Follow these steps to configure an OAuth page for external users:

  1. From the Google Cloud Platform dashboard, select OAuth consent screen.
  2. Choose the External user type and click Create.
  3. Fill out the required OAuth consent information and enter nylas.com as an Authorized domain.
  4. Click Save and continue.
  5. Select Add or remove scopes, and add the .../auth/userinfo.email, .../auth/userinfo.profile, and openid scopes.
  6. Select the scopes needed for your application.
  7. Skip the Test users step for now.
  8. Review the Summary and ensure the information is correct.
  9. Click Back to dashboard.
  10. Under Publishing status, click Publish app. A close-up of the Google Cloud Platform "External app" dialog. The "Publishing status" and "User type" options are displayed.

When you publish your Google provider auth app, you must authorize your end users with the Nylas APIs instead of adding them to Google individually as test users. The app is listed as unverified until you complete Google’s security review process.

Create Google application credentials

You need your GCP app’s client ID and client secret to use the application with the Nylas APIs.

  1. From the Google Cloud Platform dashboard, select Credentials.
  2. Click Create credentials and choose OAuth client ID from the list. The Google Cloud Platform Console showing the "Credentials" page. The "Create credentials" drop-down list is expanded, and the "OAuth client ID" option is highlighted.
  3. Set the Application type to Web application.
  4. Give the application a name.
  5. Update the Authorized redirect URIs:
    • U.S. Hosted auth: https://api.us.nylas.com/v3/connect/callback
    • E.U. Hosted auth: https://api.eu.nylas.com/v3/connect/callback
    • Custom auth: Your project’s callback URI.
  6. Click Create. The client ID and secret are displayed in the OAuth client created notification.

Add Nylas to your Google application

Nylas recommends that you add the Nylas Support team to your GCP app as an application owner. This helps the team diagnose any issues that you might encounter.

  1. From the Google Cloud Platform dashboard, open the navigation menu and select IAM & admin > IAM. Google Cloud Platform dashboard navigation menu. The "IAM and Admin" list is expanded, and "IAM" is highlighted.
  2. Click Add.
  3. Add [email protected] as an owner.
  4. Click Save.

Add the “Sign in with Google” button

Your GCP project must include a “Sign in with Google” button that meets Google’s branding guidelines. This applies to the OAuth flow for both personal Gmail (@gmail.com) and Workspace email addresses.

For Hosted authentication in v3, Nylas recommends you do one of the following:

  • Configure the OAuth login prompt by setting the prompt parameter with select_provider or detect,select_provider. For more information, see Configuring the OAuth login prompt.
    • If you add a login_hint that is a personal Gmail or Workspace email address and you don’t configure a prompt during the Hosted auth flow, the end user is immediately directed to the Google OAuth screen, without clicking the “Sign in with Google” button. This can result in delays or failure in verification.
  • Use the pre-approved “Sign in with Google” button with the “Connect your account” button or other provider login buttons in your application. For more information, see Google’s official Sign in with Google branding guidelines.

For Custom auth, use the pre-approved “Sign in with Google” button with the “Connect your account” button or other provider login buttons in your application.

For more information, see the Google verification and security assessment guide.

Add a connector to your Nylas application

Your Nylas application communicates with external provider auth apps using connectors. You can create a Google connector by copying the cURL request below and substituting your client ID, secret, and Pub/Sub topic name.

curl -X POST https://api.us.nylas.com/v3/connectors \
--header 'Authorization: Bearer <NYLAS_API_KEY>' \
--header 'Content-Type: application/json' \
--data '{
"name": "google example",
"provider": "google",
"settings":
{
"client_id": "<GCP_CLIENT_ID>",
"client_secret": "<GCP_CLIENT_SECRET>",
"topic_name": "<PUBSUB_TOPIC_NAME>"
},
"scope": [
"openid",
"https://www.googleapis.com/auth/userinfo.email",
"https://www.googleapis.com/auth/userinfo.profile",
"https://www.googleapis.com/auth/calendar",
"https://www.googleapis.com/auth/gmail.compose",
"https://www.googleapis.com/auth/gmail.modify"
]
}'