You can connect user inboxes through Nylas in two ways, and the choice decides who runs the authorization flow: Nylas, or your own app. This page compares Nylas-hosted OAuth against a custom OAuth flow, and covers the separate question of whose provider app sits behind either one, so you can decide before you write any auth code.
Both paths create grants against a connector and return the same grant ID. In production, that connector holds the credentials for your own Google and Azure apps in both cases. The one exception is Google, where the paid Nylas Google Shared App can stand in for your own Google Cloud project.
What’s the difference between hosted and custom OAuth?
Section titled “What’s the difference between hosted and custom OAuth?”With hosted OAuth, Nylas runs the authorization flow. You redirect the user to /v3/connect/auth, Nylas sends them through the provider’s sign-in and consent screens, and you exchange the returned code with POST /v3/connect/token. With custom OAuth (Bring Your Own Authentication), you run the OAuth flow against your provider app yourself, then pass the user’s refresh_token to POST /v3/connect/custom to create the grant.
The word “hosted” describes the authorization flow, not the OAuth application behind it. The consent screen, scopes, and verification status come from the provider app on your connector, and that’s the same app whichever flow you pick. Setting up a connector with your own credentials takes a single POST /v3/connectors call, covered in connect your own OAuth app.
When should I use Nylas-hosted OAuth?
Section titled “When should I use Nylas-hosted OAuth?”Nylas-hosted OAuth fits most integrations, from the first prototype through production. You don’t build a login page, handle provider redirects, or exchange provider codes yourself. Nylas recommends it for most server-side integrations.
While you’re prototyping, a Sandbox application comes with a limited set of pre-configured connectors, so you can connect a test inbox before you register anything at Google or Microsoft. You can’t create connectors or change scopes on a Sandbox application, so a production application needs a connector with your own provider app credentials (or the Google Shared App for Google). The full user-facing flow, including the state parameter and per-tenant grant storage, lives in connect user accounts with OAuth.
When should I use a custom OAuth flow?
Section titled “When should I use a custom OAuth flow?”A custom flow fits teams that already run their own OAuth flow, want full control over the login experience, or are migrating users who already have refresh tokens. You keep your existing provider integration and hand Nylas the refresh_token, so users don’t have to go through a second consent step. Bring Your Own Authentication requires an annual Pro plan.
Either way, most apps build connectors for Google and Microsoft, then add Yahoo or others as needed. With your own provider apps on those connectors, you own the Google OAuth verification (or security assessment for restricted scopes) and the Azure admin-consent posture directly. For Google, the connector’s settings object is also where you set the Pub/Sub topic_name, which the connector needs if you use email webhooks. See set up Google Pub/Sub.
Does the consent screen branding change?
Section titled “Does the consent screen branding change?”The provider consent screen shows whichever OAuth app is on your connector. With your own Google and Azure apps, it shows your app name, logo, and support details in both the hosted and the custom flow, because the OAuth client ID belongs to you. With a Sandbox application’s pre-configured connectors or the Google Shared App, the consent screen shows “Nylas”.
Users read the consent screen carefully when granting mailbox access, so the requesting app name carries real weight. A screen that names your product tells users they’re connecting to the service they signed up for. The hosted flow adds a Nylas-hosted login page in front of the provider redirect. To replace the Nylas logo there and drop nylas.com from the browser, see whitelabel Hosted Authentication. A custom hostname requires your own Google Cloud project, so it doesn’t work with the Google Shared App.
Who owns provider verification and rate limits?
Section titled “Who owns provider verification and rate limits?”Verification and rate-limit ownership follow the provider app on your connector, not the flow. With your own provider apps, you complete Google’s OAuth verification and Microsoft’s admin consent yourself, and the provider’s quotas apply to your app. With the Google Shared App, Nylas owns the Google Cloud project and has already completed Google’s verification and CASA assessment, and the consent screen shows “Nylas”.
Google sorts its scopes into 3 tiers, and restricted ones such as gmail.modify require a security assessment that attaches to your OAuth app. The Google Shared App is the alternative to running that assessment yourself, and it’s available on the annual Pro plan with the Accelerator add-on or as an Enterprise add-on. See OAuth scopes for email and calendar for which scopes trigger verification.
Hosted vs custom OAuth decision matrix
Section titled “Hosted vs custom OAuth decision matrix”The right choice depends on whether you already run an OAuth flow, and the provider app question is separate from it. The table below compares the 2 flows across the factors that drive the decision, so you can match each row to your situation rather than look for a single winner.
| Factor | Nylas-hosted OAuth | Custom OAuth (Bring Your Own Authentication) |
|---|---|---|
| Who runs the flow | Nylas hosts login and redirect; you exchange code | You: full OAuth flow, then POST /v3/connect/custom |
| Provider app | Your own, on a connector, or the Google Shared App | Your own, on a connector |
| Consent screen brand | Your app, or “Nylas” with the Google Shared App | Your app |
| Verification owner | You, or Nylas with the Google Shared App | You |
| Best for | Most integrations | Existing OAuth flows, migrating users |
Neither flow locks you in, because both create grants against the same connector. Changing the provider app is different: users who authenticated through your own Google Cloud project need to re-authenticate when you switch to the Google Shared App. The hosted OAuth with an API key reference documents the hosted token exchange.
What’s next
Section titled “What’s next”- Connect user accounts with OAuth for the user-facing hosted flow
- Connect your own OAuth app to create a connector with your credentials
- Hosted OAuth with an API key for the full token exchange both paths use
- OAuth scopes for email and calendar for which scopes need provider verification
- Authentication overview for the complete grant model