Skip to content
Docs
or

Bulk authentication grants and Service Accounts

A bulk authentication grant (also called a “Service Account”) is a type of grant that allows Nylas applications or compute workloads access to permitted resources. Nylas applications use bulk authentication grants to make authorized API calls.

Bulk authentication is available for Plus plans only.

Nylas supports two types of bulk auth grants: Microsoft and Google. For more information about Service Accounts, see Microsoft’s official documentation and Google’s official documentation.

Before you begin

Ensure that your Nylas application has a working Google or Microsoft connector. You can check this on the Nylas Dashboard, or make a Get all connectors request to get a list of connectors associated with your application.

If you don’t have a connector, create one from the Dashboard or make a Create Connector request.

Create Google bulk authentication grants

Make a Custom Authentication request that uses your Google connector’s id.

Create Microsoft bulk authentication grants

To create Microsoft bulk auth grants, you need to do the following tasks:

  1. Create and configure an Azure auth app.
  2. Set up Microsoft Admin Consent flow.
  3. Create a Microsoft bulk auth grant.

Create and configure Azure auth app

First, you need to create an Azure auth app, then configure it as follows:

  1. From the Authentication tab, click Add a platform.
  2. Set the Platform to Web and enter the Custom Auth URI.
  3. In the Certificates & secrets tab, click New client secret and add a client secret.

    Be sure to save the client secret somewhere secure, like a secrets manager. The Microsoft Azure Dashboard shows the client_secret value only once. If you lose it, you’ll need to create a new one.

  4. In the API permissions tab, click Add a permission and select Microsoft Graph from the list of APIs.
  5. Select Application permissions and add all the Microsoft Graph scopes that your project needs access to, including User.Read.All. This gives your bulk auth grant the access it needs.

You don’t need to select Grant admin consent. You can add this later using an authorization request.

Make a Create Credential request to create a unique connector credential for the bulk auth grant. The request body must include the provider’s client_id and client_secret, and can include the tenant.

You can set the tenant to common in your bulk auth requests instead of creating custom admin consent URLs for each of your customers. When you do this, you grant your project access to the Microsoft Graph scopes set by your Azure auth app, but you can’t specify scopes in the admin consent URL. If you want to set custom scopes in the admin consent URL, you need to specify your customer’s Azure tenant ID in your API requests.

If you don’t define the client_id and client_secret, Nylas uses the credentials from your application’s Microsoft connector.

Create Microsoft bulk auth grant

First, make an OAuth Authorization request using the admin profile of the Microsoft Azure OAuth app to request administrator approval for the scopes that you requested when you created the app.

Nylas redirects the Service Account to the redirect_uri. The response URL contains admin_consent:true and the contents of the state parameter (if you set one). If the flow fails, Nylas returns a normal OAuth 2.0 error that includes the state, error, error_description, and error_uri.

If your administrator approves an updated set of scopes in your Authorization request, you need to wait at least 5 minutes before creating a grant. This allows Microsoft to update its cached scopes.

Next, make a Custom Auth request to create an application permission grant. This is a Microsoft app permission account within the Nylas platform that has access to the authorized scopes and an email address used to access Microsoft Azure.