Only show these results:

Create a Google authentication application for Nylas v3

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

v3 updates

  • The Authorized redirect URIs have been updated:
    • For U.S. Hosted authentication use https://api.us.nylas.com/v3/connect/callback.
    • For E.U. Hosted authentication use https://api.eu.nylas.com/v3/connect/callback.
  • Added a cURL request example to connect your Google Cloud Platform (GCP) app to Nylas.
  • If you are using the Nylas Email APIs with Google, you must also set up a Google PubSub queue.

Before you create your application with Google, there are a few things to keep in mind.

Hosted or Native authentication

You'll first need to decide which method of authentication works for you.

Hosted authentication

This is the fastest way to get started. If you aren't interested in customizing your application, or want to test with a few users, use Hosted Authentication.

Native authentication

Use this method if you'd like to customize your application. This means your users will see your company name instead of Nylas on the OAuth screen. Native Authentication requires that you have an application built with a callback URL.

We also recommend reviewing our Google Authentication Guide.

Switching Authentication Methods

Switching between Hosted and Native Authentication will require a new application and for accounts to be re-authenticated.

Internal or external application

You'll also need to decide if you want your application available to anyone or only users that are part of your organization.

Internal application

For any development or production applications that are for internal use only, we recommend using internal users for Google account access. Only users who have an account within your organization (for example, any user with an @nylas.com email address) can access the application.

When users from your organization authorize against your application, they won't see the unverified application warning.

Use internal applications to skip the app verification and security review process. If anyone outside your organization needs to verify against your application at any time, you'll need to go through Google's security review.

External application

For any production applications that will need to go through Google's security verification, use external users. This option will allow users who aren't from your organization to authenticate against your application.

When users from your organization authorize against your application, they'll see the unverified application warning.

External apps are limited to 100 accounts before verification.

Learn more about unverified apps at Google.

Create a Google application

💡 Nylas recommends you use separate GCP apps for your production and test environments. Even small changes on a verified GCP app could trigger a new verification process, so having a separate app for your test environment gives you flexibility to test without interrupting your production users.

Follow the steps below to create your GCP 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 populated with sample 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 GCP app to work with Nylas API v3. Follow these steps to enable them:

  1. From the Google Cloud Platform dashboard, select APIs and services.
  2. Click Enable APIs and services.
    Google Cloud Platform "APIs and Services" page.
  3. Search for and enable the following APIs:
    • Gmail API: Required to read and send email messages. Also required for the Threads, Drafts, Folders, Files, and Neural endpoints.
    • Google Calendar API: Required to use the Calendar and Events endpoints, and for Scheduler.
    • People API: Required to use the Contacts endpoints.
    • Admin SDK API: Optional. Grants access to room information for calendar events.

Google authentication scopes

The table below lists the available Google auth scopes.

Google Scope URI Description
https://www.googleapis.com/auth/userinfo.email Required Google scope.
https://www.googleapis.com/auth/userinfo.profile Required Google scope.
openid Required Google scope.
https://www.googleapis.com/auth/gmail.modify Read, compose, and send email messages from a Gmail account.
https://www.googleapis.com/auth/gmail.readonly View email messages.
https://www.googleapis.com/auth/gmail.labels View and edit Gmail labels.
https://www.googleapis.com/auth/gmail.compose Create drafts and send email messages.
https://www.googleapis.com/auth/gmail.send Send email messages.
https://www.googleapis.com/auth/calendar View, create, edit, and delete calendars and events.
https://www.googleapis.com/auth/calendar.readonly View calendars and events.
https://www.googleapis.com/auth/calendar.events View and edit events on all calendars.
https://www.googleapis.com/auth/calendar.events.readonly View events on all calendars.

📝 Note: If your GCP app uses the gmail.readonly or gmail.labels scopes, you must set up Pub/Sub. This ensures that you get real-time updates from your app.

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

Automatically include previously granted scopes

Nylas includes Google's special 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 authentication process for your end users, because they're no longer required to re-select the scopes they already approved when they authenticate again.

Configure OAuth page

You can configure your GCP app's OAuth page for both internal and external users. This is the page that your end users will see when they authenticate your application.

Configure internal OAuth page

Follow these steps to configure an internal OAuth page:

  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 external OAuth page:

  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.
    The "Publishing Status" and "User Type" sections for a GCP app's external OAuth page.

Publishing your GCP app sets it so you must authorize users with the Nylas APIs instead of adding them individually to Google as test users. The app is listed as unverified until you complete the Google security review.

Create credentials

You need your GCP app's client ID and secret to use your app with the Nylas APIs. Follow these steps to create them:

  1. From the Google Cloud Platform dashboard, select Credentials.
  2. Click Create credentials and choose OAuth client ID from the list.
    Google Cloud Platform "Credentials" page. The "Create Credentials" list is shown.
  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 Nylas application's callback URI.
  6. Click Create. The client ID and secret are displayed in the OAuth client created notification.

    ⚠️ Be sure to save your client ID and secret somewhere safe.

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 may 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 Pub/Sub to your Google application

🔍 If you plan to use the Nylas Email API with Google, you must set up Pub/Sub. If you don't plan to use the Nylas Email API with your GCP app (for example, if you're a calendar-only project), you can skip this step.

Google's Pub/Sub subscription service allows you to receive webhook notifications from Google in a timely manner. You can either use the Nylas-maintained set up script to add Pub/Sub to your app, or set it up manually.

Add Pub/Sub with the Nylas setup script

To simplify Pub/Sub installation, Nylas maintains a script that you can run to automatically provision the GCP resources in Golang.

Before you use the script, make sure your environment is set up properly:

  • Install the Go language.

  • Install the Google Cloud CLI tool.

  • Ensure that the Pub/Sub and IAM APIs are enabled in your GCP app. You can do this using the gcloud CLI:

    gcloud services enable pubsub.googleapis.com
    gcloud services enable iam.googleapis.com

⚠️ Your Pub/Sub topic and its related resources must be set up in the Google auth app that you use to authenticate accounts with Nylas.

When your environment is ready, download and run the Nylas script:

  1. Download the script from the Nylas infra-setup repository and change your local directory to google-pubsub-sync.

    git clone https://github.com/nylas-samples/infra-setup
    cd infra-setup/google-pubsub-sync
  2. Use the gcloud CLI to switch the project setup to your GCP project.

    gcloud config set project $YOUR_GOOGLE_PROJECT_ID   
  3. Authenticate with your GCP app. Make sure that the account you authenticate with has permission to create Pub/Sub and IAM resources.

    gcloud auth login
    gcloud auth application-default login
  4. Fetch the dependencies for the script.

    go get .   
  5. Run the script.

    go run main.go --projectId $YOUR_GCP_PROJECT_ID   
    • If you want to configure your GCP app in an environment other than the U.S., use the --env flag, as in the code snippet below. The flag supports the us, eu and staging values.

      go run main.go --projectId $YOUR_GCP_PROJECT_ID --env eu   
  6. Save the topic name. You'll use it again when you create your Nylas connector.

If the script fails with a 403 error with a SERVICE_DISABLED message, make sure to enable both the IAM and Pub/Sub APIs in your project using the gcloud CLI:

gcloud services enable pubsub.googleapis.com
gcloud services enable iam.googleapis.com

Manually add Pub/Sub

To manually add Pub/Sub to your GCP app, you must create a service account and subscribe to a Pub/Sub topic.

Create a Google service account

First, create a service account in your GCP app:

  1. From the Google Cloud Platform dashboard, navigate to IAM & admin > Service accounts.
  2. Select your project and click Create service account.
  3. Name the account nylas-gmail-realtime.

    ⚠️ The service account name must be exactly nylas-gmail-realtime for the Nylas connector to work.

  4. Optionally, add a description to the service account.
  5. Click Create and continue.
  6. Leave the Grant this service account access to project section blank and click Continue.
  7. Leave the Grant users access to this service account section blank.
  8. Click Done.

The following video walks through the process of creating a service account in the Google Cloud Platform dashboard.

Create a Pub/Sub topic

Next, create a Pub/Sub topic and subscribe to it.

⚠️ Your Pub/Sub topic and its related resources must be set up in the Google auth app that you use to authenticate accounts with Nylas.

  1. From the Google Cloud Platform dashboard, search for "pub/sub" and select Pub/Sub.
  2. Click Create topic.
  3. Enter nylas-gmail-realtime as the topic ID, and leave everything else as it is.

    ⚠️ The topic ID must be exactly nylas-gmail-realtime for the Nylas connector to work.

  4. On the next page, click Show info panel if the panel is not already open.
  5. In the info panel, click Add principal.
  6. Enter [email protected] in the New principals field and set the role to Pub/Sub publisher.
  7. On the Topics page, find the Subscription section and click nylas-gmail-realtime-sub.
  8. Select the subscription and click Edit.
  9. Change the Delivery type to Push.
  10. Set the Endpoint URL:
    • For the U.S., use https://gmailrealtime.us.nylas.com.
    • For the E.U., use https://gmailrealtime.eu.nylas.com.

    📝 If you're setting up multiple regions in a single GCP app, you must create a Pub/Sub subscription for each region.

  11. Select Enable authentication and choose the nylas-gmail-realtime service account.
  12. When prompted, grant the account the roles/iam.serviceAccountTokenCreator role. If the prompt doesn't appear, follow these steps to add the role manually:
    1. From the GCP dashboard, select IAM & admin > Service accounts.
    2. Copy the full email address for the nylas-gmail-realtime service account. The email address should start with nylas-gmail-realtime.
    3. Select the service account.
    4. Navigate to the Permissions tab, then find the Principals tab at the bottom of the section.
    5. Find the nylas-gmail-realtime-email service account and click the Edit symbol next to it.
      • If the service account isn't listed, click Grant access and paste the email address in the New principals field.
    6. A pop-up is displayed. Click Add another role.
    7. Search for service account token creator and select the role.
    8. Click Save.
  13. Under Expiration period, select Never expire.
  14. Leave the other fields as they are and click Update. Google saves your changes, and you're returned to the Subscription page.
  15. Save the topic name. You'll use it again when you create your Nylas connector.

Add the "Sign in with Google" button

Your Google application must have the "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.

    ⚠️ Keep in mind: If you add a login_hint that is a personal Gmail or Workspace email address and 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 in v3, use the pre-approved "Sign in with Google" button with the “Connect your account” button or other provider login buttons in your application.

Learn more about Google verification and security assessment.

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": "<google_client_id>",
"client_secret": "<google_client_secret>",
"topic_name": "<google_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"
]
}'

What's next?

If you've made it this far, congrats! You've learned how to create and configure a Google auth app. 🎉

Next, Nylas recommends creating a test application in the v3 Nylas Dashboard. You can also check out the following topics for more information about authentication in Nylas: