You’re building a SaaS app, and every user needs to connect their own Gmail or Outlook account. The old approach meant collecting passwords, storing refresh tokens, and rebuilding the OAuth flow for each provider. Nylas replaces that with one hosted authorization flow that returns a grant ID you reuse across every provider.
This recipe answers the OAuth questions developers ask most often: which flow to use, what scopes to request, how token refresh works, where credentials live, and how to revoke access when someone disconnects.
How does OAuth work with the Nylas APIs?
Section titled “How does OAuth work with the Nylas APIs?”Hosted OAuth sends the user to a single authorization URL, they approve access at their provider, and a grant ID comes back representing their connected account. You make every API call with that grant ID plus your API key, so your app never handles the user’s password or provider tokens directly. One integration covers six providers: Google, Microsoft, Yahoo, iCloud, IMAP, and Exchange.
The hosted flow has seven steps, from the user clicking “Connect” to a verified grant. Your app starts it by redirecting the user to the authorization endpoint at /v3/connect/auth with your client ID and callback URI. The request below shows the query parameters that begin a session.
GET https://api.us.nylas.com/v3/connect/auth? client_id=<NYLAS_CLIENT_ID> &redirect_uri=https://myapp.com/callback &response_type=code &provider=google &state=<PER_USER_STATE>After the user approves, the provider redirects back to your callback with a code. You exchange that code for the grant at /v3/connect/token. The hosted OAuth with API key guide walks through the full exchange with runnable SDK examples.
How do I let each user connect their own inbox?
Section titled “How do I let each user connect their own inbox?”Send each user through the same hosted flow and use the state query parameter to track who is connecting. When the callback fires, match the returned state back to your user record, then store the grant ID against that account. This pattern scales to any number of tenants because one redirect URL serves every user, and each completed flow produces a separate grant.
The SDK builds the redirect URL for you. The urlForOAuth2 method takes your client ID, the provider, your callback URI, and an optional loginHint that fills in the user’s email address. Generate the URL per user, then redirect.
const authUrl = nylas.auth.urlForOAuth2({ clientId: process.env.NYLAS_CLIENT_ID, provider: "google", redirectUri: "https://myapp.com/callback", loginHint: user.email, state: user.id,});
res.redirect(authUrl);What OAuth scopes do I need?
Section titled “What OAuth scopes do I need?”Scopes are the permissions you request from each user, set per provider. Request only what your features use: read-only messages need a narrower scope than send-and-modify. Google sorts its scopes into three tiers (non-sensitive, sensitive, and restricted), and the higher tiers require OAuth verification or a security assessment before launch.
The exact scope strings differ by provider and endpoint. The granular scopes reference lists the required and optional scopes for every Nylas API, including the full provider URI prefixes. For example, reading Gmail messages requires gmail.readonly, while modifying or deleting them requires gmail.modify. IMAP connectors are the exception: they authenticate with credentials and don’t use scopes at all.
How does Nylas handle token refresh?
Section titled “How does Nylas handle token refresh?”Token refresh is automatic. Nylas stores the provider’s access and refresh tokens on the grant and refreshes the underlying token before it expires, so long-lived integrations keep working without any refresh code in your app. A grant stays valid until the user or the provider revokes it.
You control this at authorization time with access_type. The default issues a refresh token for offline access, which is what most server-side integrations want. Setting access_type=online skips the refresh token, so access ends when the session token expires. Per the best practices guide, your project should hold only one active access token per grant at any time.
What’s the most secure way to store OAuth credentials?
Section titled “What’s the most secure way to store OAuth credentials?”You never store provider OAuth tokens. Your app keeps only two values: the grant ID, a non-secret identifier for the connected account, and your API key, a server-side secret used for every request. Provider access and refresh tokens stay on the Nylas side, which removes the riskiest credentials from your database entirely.
Keep the API key in a secrets manager or environment variable, never in client-side code or a public repository. Scope database access to the grant IDs so a leaked record exposes an identifier, not a usable token. This split means a compromise of your application database doesn’t hand an attacker working access to user inboxes.
How do I revoke a user’s access?
Section titled “How do I revoke a user’s access?”Revoke access with a single POST /v3/connect/revoke request that takes the access token as a query parameter. Revoking a Nylas access token also revokes all its child tokens. Call this whenever a user disconnects their account, re-authenticates, or cancels, so a stale token is never left active.
The request authenticates with your API key and passes the token to revoke. The revoke OAuth token reference documents the full response codes, including the 400 returned when a token is already expired.
curl --request POST \ --url 'https://api.us.nylas.com/v3/connect/revoke?token=<ACCESS_TOKEN>' \ --header 'Accept: application/json' \ --header 'Authorization: Bearer <NYLAS_API_KEY>'OAuth 2.0 versus IMAP authentication
Section titled “OAuth 2.0 versus IMAP authentication”OAuth 2.0 is token-based: the user approves scoped access at their provider and no password reaches your app. IMAP authentication uses the mailbox credentials or an app-specific password and applies to providers without a modern OAuth option. The table compares the two so you can pick per connector.
| Property | OAuth 2.0 | IMAP |
|---|---|---|
| Credentials | Token, approved by the user | Username and password or app password |
| Scopes | Granular, per provider | Not supported |
| User experience | Provider consent screen | Credential entry |
| Best for | Google, Microsoft, Yahoo, iCloud, Exchange | Generic IMAP servers |
| Revocation | POST /v3/connect/revoke | Rotate or remove the credential |
For IMAP specifics, including app-password requirements, see creating grants with IMAP authentication.
What’s next
Section titled “What’s next”- Authentication overview for the full grant model and every auth method
- Hosted OAuth with an API key for the complete token exchange
- Granular scopes reference for the exact scope strings per API
- Authentication best practices for token handling and grant hygiene