Connect a user's mailbox with Nylas hosted OAuth

Every Nylas request you make on a user's behalf needs one thing first: their permission. Before you can list a mailbox, send on someone's behalf, or read a calendar, the user has to authorize your application through their provider, and that authorization is what's called a grant. Doing the OAuth dance yourself means registering with Google and Microsoft separately, handling each provider's consent screen, token exchange, and refresh quirks. Hosted OAuth collapses that into one flow that works the same across every provider.

This post walks through connecting an account from two angles: the HTTP API your web app uses in production, and the with a few query parameters. You pass your client_id, the redirect_uri where the user is sent back after authorizing, response_type=code to request an authorization code, and a provider to skip the provider-picker when you already know it. You construct this URL and redirect the user's browser to it. It's shown expanded across lines below for readability; in practice it's a single URL with the redirect_uri percent-encoded.

https://api.us.nylas.com/v3/connect/auth?

  client_id=<NYLAS_CLIENT_ID>

  &redirect_uri=https://yourapp.com/callback

  &response_type=code

  &provider=google

  &access_type=online

The access_type parameter is worth a deliberate choice. Set it to online and Nylas doesn't generate a refresh token, which suits a session where the user is present; set it to offline when your application needs ongoing background access to the mailbox after the user leaves. After the user consents, they're redirected back to your redirect_uri with ?code=<AUTH_CODE> appended, and that code is what you exchange next.

Exchange the code for a grant

Your callback handler receives the code and exchanges it server-side with lists every grant on your application, and removes the connection on the Nylas side, after which the grant_id no longer works and you stop being able to access that mailbox. Deleting a grant is the clean way to honor a user's disconnect request, since it severs the stored authorization entirely.

curl --request DELETE \

  --url "https://api.us.nylas.com/v3/grants/<GRANT_ID>" \

  --header "Authorization: Bearer <NYLAS_API_KEY>"

The CLI equivalent is nylas auth revoke, which revokes a grant from the server, and nylas auth logout for the active one. There's a distinction worth knowing: nylas auth remove drops a grant from your local CLI config without revoking it on the server, while revoke actually severs the connection. Use revoke when you mean to disconnect the account, not just forget it locally.

When a grant goes stale

A grant isn't permanent. A user can revoke access at their provider, change their password, or hit a provider policy that invalidates the connection, and when that happens the grant's grant_status reflects it rather than the grant_id silently failing. The grant object carries a grant_status field, valid or invalid, so a quick fetch tells you whether a connection is still healthy, and Nylas emits a grant.expired webhook so your application learns about a broken connection without polling for it.

The fix for a stale grant is to reconnect, not to delete and recreate. You send the user back through the same hosted OAuth flow, and the refreshed authorization restores access for that account. Wiring up the grant webhooks means you can prompt exactly the users who need to re-authenticate, instead of discovering broken connections one failed request at a time. That's the difference between a user noticing their integration broke and your application catching it first.

Online versus offline access

The access_type choice from the auth URL has consequences worth understanding. With access_type=online, no refresh token is generated, so the grant is suited to flows where the user is actively present and you don't need to touch the mailbox once they leave. It's the lighter-weight option when you're acting in direct response to a user.

For most production integrations you want ongoing access, an agent that processes mail overnight or a sync that runs on a schedule. There you set access_type=offline so the grant gets a refresh token and can maintain access without the user being present. Nylas handles the token refresh underneath, so you don't manage refresh tokens yourself; the grant stays valid and your grant_id keeps working. Choosing the wrong mode shows up later: an online grant can't be refreshed for background use and stops working once its access token expires unless the user re-authenticates, so set it intentionally up front.

Things to keep in mind

A few practices keep an authentication integration solid from the first grant onward.

• 
  Exchange the code server-side. The token exchange carries your credentials, so it belongs on your backend, never in browser-side code.


• 
  Store the grant_id, not the code. The code is single-use and short-lived; the grant_id is the durable handle you keep against your user.


• 
  Pick access_type deliberately. Use online for present-user flows and offline for background access; the wrong choice surfaces as a grant that expires unexpectedly.


• 
  Check scopes when a call is forbidden. nylas auth scopes or the grant object tells you what the user actually authorized.


• 
  Revoke, don't just forget. Deleting a grant or nylas auth revoke severs access; removing it locally only hides it from your config.


• 
  Detect the provider to skip a step. Pass provider on the auth URL, or use nylas auth detect, so the user skips the chooser and lands on the right consent screen.

Wrapping up

Connecting a mailbox is one flow with three steps: redirect to the authorization URL, receive a code at your callback, and exchange it for a grant_id. From there the provider differences vanish, and every Email, Calendar, and Contacts call uses the same identifier. For development, nylas auth login runs the whole flow from the terminal so you have a real grant in seconds, and the Grants API plus nylas auth commands let you list, inspect, and revoke connections as users come and go.

Where to go next:

• 
  — the full flow with code samples in several languages


• 
  — the Grants API references


• 
  Nylas CLI — nylas auth login, list, scopes, and revoke