Connect your own OAuth app

In production, every connector holds your own provider app credentials. The provider consent screen shows your app, you choose the scopes it requests, and the verification is the one you completed with Google or Microsoft. A Sandbox application comes with pre-configured connectors for testing, and for Google, the paid Google Shared App can stand in for your own Google Cloud project.

A connector links your own OAuth application’s credentials to Nylas. Once it exists, every grant authenticated against it uses your client ID, so the consent screen shows your app and the tokens carry your scopes.

How do I connect my own OAuth app?

Create a connector with a POST /v3/connectors request. You pass the provider, a settings object with your client_id and client_secret from the provider’s developer console, and the scope array your app needs. Each Nylas application has one connector per provider, and most apps create connectors for 2 providers (Google and Microsoft).

The request below creates a Google connector with your own credentials and scopes.

curl --request POST \
  --url 'https://api.us.nylas.com/v3/connectors' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>' \
  --data '{
    "provider": "google",
    "settings": {
      "client_id": "<NYLAS_CLIENT_ID>",
      "client_secret": "<NYLAS_CLIENT_SECRET>",
      "topic_name": "<TOPIC_NAME>"
    },
    "scope": [
      "https://www.googleapis.com/auth/userinfo.email",
      "https://www.googleapis.com/auth/userinfo.profile"
    ]
  }'

Why use my own connector?

Your own connector puts your brand on the consent screen for the 2 providers most apps support (Google and Microsoft), which matters for user trust in production. It also gives you control over the exact OAuth scopes you request and lets you use the provider verification you’ve completed yourself. The provider’s quotas apply to your app. For Google, the connector’s settings is also where you set the Pub/Sub topic_name that powers native push.

A Sandbox application’s pre-configured connectors let you build and test before you register an app with Google or Microsoft, and their consent screen shows “Nylas”. You can’t create connectors on a Sandbox application, so a production application needs a connector with your own credentials, or the Google Shared App for Google. The hosted vs custom OAuth comparison covers who owns verification in each setup.

Things to know about connectors

A connector is application-scoped and provider-scoped: one per provider per Nylas application, created once and reused by every grant on that provider, so most integrations maintain connectors for 2 providers (Google and Microsoft). You rotate or update the underlying credentials through the connector’s creds sub-resource without recreating the connector, which keeps existing grants working.

Match the connector’s scope array to what your features use and to what you’ve had verified. The connector scope sets the default scopes for the consent screen, and individual grants can override them at auth time. See authentication overview for where connectors fit in the grant model.

What’s next

Authentication overview for how connectors fit the grant model
Connect user accounts with OAuth for the user-facing auth flow
OAuth scopes for the scope strings to put in the connector
Get real-time updates with webhooks which Google push uses the connector’s topic for