You can connect user inboxes through Nylas in two ways, and the choice affects what users see on the consent screen, who owns provider verification, and which app hits the rate limits. This page compares hosted OAuth against a custom connector so you can decide before you write any auth code.
Both paths use the same hosted authorization flow and return the same grant ID. The difference is whose OAuth application sits behind that flow: Nylas-owned default credentials, or your own Google and Azure apps registered through a connector.
What’s the difference between hosted and custom OAuth?
Section titled “What’s the difference between hosted and custom OAuth?”Hosted OAuth uses Nylas-owned provider apps and consent screen, so you ship without registering anything at Google or Microsoft. Custom OAuth points the same flow at your own OAuth credentials through a connector, so your brand, scopes, and verification status apply. Both produce one grant ID you reuse across all 6 providers.
The word “hosted” describes the authorization flow itself, and that flow stays identical either way. The redirect, the secure session, and the token exchange always run on the Nylas side. What a connector changes is the OAuth application behind the consent screen. With default credentials the screen reads the platform name and the underlying app is shared. With a connector the screen reads your app name, and the credentials are yours alone. Setting one up 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 prototypes, internal tools, and the first weeks of development, when you want a connected inbox in minutes. You skip provider app registration entirely and authenticate against shared default credentials. The tradeoff is a default-branded consent screen and shared provider limits, which 2 categories of project can usually accept.
Reach for the hosted default when you’re validating an idea, running an internal back-office tool where branding doesn’t matter, or building a demo. The full user-facing flow, including the state parameter and per-tenant grant storage, lives in connect user accounts with OAuth. You can start there today and add a connector later without rewriting the flow, since the grant model and the authorization endpoint stay the same across the switch.
When should I use a custom OAuth connector?
Section titled “When should I use a custom OAuth connector?”A custom connector fits any production app where users see your brand and you control verification. You register your own Google and Azure apps, then create 1 connector per provider so every grant authenticates against your client ID. This is the path for SaaS products, since the consent screen showing your name is a baseline trust signal for paying customers.
Most apps build connectors for Google and Microsoft, the 2 providers that cover the largest mailbox share, then add Yahoo or others as needed. You own the Google OAuth verification (or security assessment for restricted scopes) and the Azure admin-consent posture directly, rather than sharing default app limits. For Google, the connector’s settings object is also where the Pub/Sub topic_name for native push lives, so email webhooks effectively require a connector anyway.
Does the consent screen branding change?
Section titled “Does the consent screen branding change?”Branding is the most visible difference. With the hosted default credentials, the provider consent screen shows “Nylas” as the requesting app. With a custom connector, it shows your own app name, logo, and support details, because the OAuth client ID belongs to you. This single change is why most production apps move to a connector before launch.
Users read the consent screen carefully when granting mailbox access, so the requesting app name carries real weight. A screen that names your product reassures users that they’re connecting to the service they signed up for. A generic third-party name on the screen is a known drop-off point in 1 of the most sensitive steps of onboarding. The branded screen is unlocked entirely by the connector’s credentials, with no extra Nylas configuration.
Who owns provider verification and rate limits?
Section titled “Who owns provider verification and rate limits?”Verification and rate-limit ownership flip with a connector. On default credentials, Nylas owns the verified provider apps and you share their limits across many tenants. With your own connector, you complete Google’s OAuth verification and Microsoft’s admin consent yourself, and your client ID gets its own provider-side quota separate from every other app.
This matters most as you scale past the prototype stage. Sharing default app limits is fine for a handful of test accounts, but a growing production app wants its own quota so another tenant’s traffic never affects yours. Google sorts its scopes into 3 tiers, and restricted ones such as gmail.modify require a security assessment that attaches to your OAuth app, which only exists once you run your own connector. 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 your stage and your users. The table below compares the 2 paths across the 5 factors that drive the decision, so you can match each row to your situation rather than look for a single winner. For most teams, the answer is hosted first, then a connector before production launch.
| Factor | Nylas-hosted OAuth | Custom OAuth connector |
|---|---|---|
| Consent screen brand | Shows “Nylas” | Shows your app name and logo |
| Provider app setup | None, uses shared default credentials | Register your own Google and Azure apps |
| Verification owner | Nylas owns verified apps | You complete Google and Microsoft verification |
| Rate limits | Shared across tenants on default app | Your own provider quota per client ID |
| Best for | Prototypes, internal tools, demos | Production SaaS, branded onboarding |
Neither path locks you in. You can start on hosted default credentials and create a connector with a single POST /v3/connectors request later, and existing grants keep working because the authorization flow and grant ID format don’t change. The hosted OAuth with an API key reference documents the token exchange that both paths share.
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