Streamline Mailbox Access with Nylas Hosted OAuth Integration

Integrating a user's email mailbox into your application shouldn’t require juggling multiple OAuth providers or deciphering provider-specific consent screens. Nylas Hosted OAuth eliminates that friction by consolidating the entire authorization process into a unified flow that works seamlessly across Google, Microsoft, Yahoo, iCloud, and Exchange.

Whether you're building a production-ready web app or testing locally, understanding how grants and the OAuth dance work under the hood can save hours of development time and reduce potential security risks. This guide breaks down the hosted OAuth process into actionable steps, covering both API-driven integrations and quick CLI-based testing.

What is a grant and why it matters

A grant represents an authenticated connection between your application and a single user’s mailbox. When a user authorizes your app, Nylas generates a grant_id—a stable identifier you include in every subsequent API request to access their emails, calendar, or contacts. This grant_id acts as the bridge between your application and the user’s data, ensuring that all interactions are properly scoped and secure.

It’s crucial to distinguish between two types of credentials in this process:

• Your API key, which authenticates your application to Nylas and should remain securely on your backend server.
• The grant_id, which is generated per user and identifies the specific mailbox your application is accessing.

Under the hood, the technical details of OAuth flows differ between providers (e.g., Gmail vs. Microsoft 365), but Nylas Hosted OAuth abstracts these complexities away. Once a connection is established, every provider is treated uniformly—a single grant_id works the same way whether the mailbox is hosted on Google, Microsoft, or another service.

How the hosted OAuth flow works in three stages

Nylas Hosted OAuth follows a standard authorization-code flow, broken into three clear stages:

1. Redirect the user to Nylas for authorization

Your application constructs and directs the user’s browser to a Nylas-hosted authorization URL. This URL includes your client_id, the redirect_uri where the user will return after consenting, and a provider parameter to specify the mailbox type (e.g., google, microsoft). The response_type=code parameter requests an authorization code, which is a short-lived token used to exchange for the final grant.

1. User consents and returns with a code

The user signs into their chosen provider (e.g., Google) and grants your application access. Nylas then redirects them back to your redirect_uri, appending a code query parameter to the URL. This code is the temporary handshake between the browser and your backend—it’s not a grant itself, but a one-time-use token that proves the user authorized your app.

1. Exchange the code for a grant on your server

Your backend server exchanges the code for a permanent grant_id by calling Nylas’s token endpoint. This step must occur server-side to keep your client_secret secure. Once the exchange completes, the connection is verified, and you can use the grant_id to interact with the user’s mailbox indefinitely (or until revoked).

This structure mirrors traditional OAuth flows but simplifies implementation by handling provider-specific quirks internally.

Constructing the authorization URL for production

To initiate the hosted OAuth flow, your application must generate an authorization URL and redirect the user’s browser to it. The URL follows this structure:

Key parameters to include:

• client_id: Your Nylas application’s unique identifier.
• redirect_uri: The endpoint in your app where Nylas sends the user after authorization (must match exactly what’s registered in your Nylas dashboard).
• response_type=code: Requests an authorization code instead of an implicit token.
• provider: Limits the picker to a specific provider (e.g., google, microsoft). Omit this to show the provider selection screen.
• access_type: Choose online for session-based access or offline for long-term, background access. The latter is ideal if your app needs to sync data without user interaction.

Once the user consents, they’re redirected back to your redirect_uri with a ?code= parameter. Your backend will use this code in the next step.

Exchanging the code for a permanent grant

Your server handles the code-to-grant exchange by sending a POST request to Nylas’s token endpoint. Here’s the structure of the request:

curl --request POST \
  --url " \
  --header "Content-Type: application/json" \
  --data '{
    "client_id": "<NYLAS_CLIENT_ID>",
    "client_secret": "<NYLAS_API_KEY>",
    "code": "<AUTH_CODE>",
    "redirect_uri": "
    "grant_type": "authorization_code"
  }'

The response includes the grant_id, which you should store in your database alongside the user’s record. This ID becomes the key to all future interactions with their mailbox. The code used in this exchange is now invalid—attempting to reuse it will fail, which is a security feature to prevent replay attacks.

Testing connections quickly with the Nylas CLI

Setting up a full OAuth flow for local development can feel cumbersome, but the Nylas CLI streamlines the process. Instead of manually constructing URLs and handling redirects, you can generate a test grant in seconds:

# Connect a Google account (default provider)
nylas auth login

# Connect a Microsoft mailbox
nylas auth login --provider microsoft

# Connect an Exchange mailbox via EWS
nylas auth login --provider ews

# Connect an IMAP-based mailbox
nylas auth login --provider imap

The CLI opens the provider’s consent screen in your default browser. Once you authorize the connection, the CLI stores the resulting grant_id as your active account, ready for immediate testing. This approach bypasses the need to deploy a frontend or backend just to validate your integration.

Key takeaways for seamless integration

Hosted OAuth from Nylas transforms a traditionally fragmented process into a unified, developer-friendly experience. By abstracting provider-specific OAuth quirks, it lets you focus on building features rather than wrestling with authentication logic. Whether you’re deploying to production or iterating locally with the CLI, the hosted flow delivers consistency, security, and simplicity—all while supporting a wide range of email providers. As your application scales, the grant_id system ensures that each user’s access remains properly managed and secure.