Connect your own OAuth app

By default, the provider consent screen shows Nylas, not your brand. For a production app, you want your own name there, and you want control over which scopes you request and which verification you’ve completed with Google or Microsoft.

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.

Request

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, rather than sharing default app limits. For Google, the connector’s settings is also where you set the Pub/Sub topic_name that powers native push.

Without a custom connector you can still build and test on the default shared credentials, but you’d ship to production behind a Nylas-branded consent screen.

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