Skip to content
Skip to main content

Bulk-authenticate user accounts

Last updated:

You’re connecting an entire company, and sending 500 employees through an OAuth consent screen one at a time isn’t an option. For internal tools and enterprise deployments, the admin should be able to connect every mailbox in the domain in one move.

Nylas bulk auth does exactly that. An administrator grants access once at the organization level, and it creates grants for users across the domain without each person running an individual OAuth flow.

How do I authenticate many accounts at once?

Section titled “How do I authenticate many accounts at once?”

Bulk auth works through 2 providers (Google and Microsoft), each using that provider’s organization-level trust model. Instead of a per-user consent screen, an admin authorizes Nylas for the whole domain, and you create grants programmatically for any user in it. It’s built for internal apps and enterprise deployments where one admin speaks for many mailboxes.

This is a plan-gated feature, so confirm it’s enabled for your Nylas application first. See bulk authentication for the full setup on both providers.

How does bulk auth work on each provider?

Section titled “How does bulk auth work on each provider?”

The 2 providers use different organization-level trust models. Google bulk auth uses a Google Workspace service account with domain-wide delegation: a Workspace admin grants the delegation once in the Admin console, and the service account’s private key lets Nylas request an access token for any user in the domain. Microsoft bulk auth uses admin consent instead, where a Microsoft 365 tenant administrator consents to your application’s permissions once for the whole tenant.

The mechanism differs, but the outcome matches on both providers: one admin authorization replaces every individual consent screen. Once it’s configured, you create a grant for a given domain user with a single Custom Authentication request, referencing the connector credential, and Nylas handles the token exchange. As the authentication methods diagram shows, a request for a user who already has a grant on that connector re-authenticates it and keeps the same grant ID.

How each authentication method creates a grant

Every method ends with a grant ID that your app uses in API requests. With bring your own auth, your app owns the provider OAuth flow and hands Nylas the tokens. If a grant already exists for the same email and connector, Nylas re-authenticates it and keeps its ID.
Diagram as text
  • One of these paths:
    • Hosted auth
      • Your app: Send the user to Nylas: Redirect to /v3/connect/auth with your client_id and redirect_uri. Add a code_challenge for PKCE.
        • Optional parameter provider: skip the provider picker. Without it, Nylas shows a hosted page where the user chooses.
        • Optional parameter login_hint: prefill the user's email address.
        • Optional parameter scope: request specific scopes. Without it, Nylas uses the connector's default scopes.
        • Optional parameter state: a value Nylas returns to you after sign-in.
      • User: Signs in: On the provider's consent screen (Google, Microsoft, Yahoo, Zoom), or in a Nylas-hosted form for IMAP, iCloud, and EWS passwords.
      • Your app: Exchange the code: POST /v3/connect/token with the one-time code, plus the code_verifier for PKCE. (code sent to your redirect_uri)
    • Bring your own auth
      • Your app: Run your own OAuth flow: Send the user to the provider's consent screen with your own OAuth app.
      • Provider: Returns tokens: Your app receives the user's refresh token.
      • Your backend: Send the tokens to Nylas: POST /v3/connect/custom with the refresh token, or IMAP credentials, and your API key.
    • Agent Account
      • Your backend: Create the account: POST /v3/connect/custom with provider set to "nylas". Nylas creates the mailbox, with no user sign-in.
  • Nylas: Existing grant?: Nylas looks for a grant with the same email and connector.
  • Ends in one of:
    • No match → New grant ID: The grant starts as valid. Nylas sends grant.created.
    • Match found → Same grant ID: Nylas re-authenticates the grant and sends grant.updated with reauthentication_flag: true.

The exact permissions and steps for each provider are in the bulk auth reference.

What’s next

Section titled “What’s next”