Bulk authentication grants

Bulk Authentication is available for Contract plans only.

Bulk authentication grants let you authenticate users without requiring each person to go through an individual OAuth flow. This is useful when you need to access mailboxes or calendars for many users in an organization.

Google and Microsoft use different mechanisms for this:

Google uses service accounts with domain-wide delegation. A Google Workspace admin grants your service account access to user data across the domain.
Microsoft uses admin consent. An Azure AD admin approves your app’s requested permissions for all users in the tenant. You don’t need to create a service account or generate new keys — you use your existing Azure app’s client ID and secret.

Both flows require you to register your provider credentials with Nylas using the Create Credential API, then create grants for individual users using the Custom Authentication API.

These are not related to Nylas Service Accounts, which use cryptographic request signing for organization-level admin APIs.

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.

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

Create Google bulk authentication grants

Google bulk auth grants use a Google Workspace service account with domain-wide delegation. The service account’s private key lets Nylas request access tokens for any user in the domain without individual OAuth flows.

Create a Google service account and delegate domain-wide authority.
Register the service account with Nylas.
Create a grant for a user.

Step 1: Create a Google service account

Follow the Google provider guide to create a service account and delegate domain-wide authority. You’ll need the service account’s JSON key file for the next step.

Step 2: Register the service account with Nylas

Make a Create Credential request to register your Google service account with Nylas. Include the service account details from the JSON key file you downloaded.

curl --request POST \
  --url 'https://api.us.nylas.com/v3/connectors/google/creds' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json, application/gzip' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>' \
  --data '{
    "name": "Test Google service account credential",
    "credential_type": "serviceaccount",
    "credential_data": {
      "type": "service_account",
      "project_id": "marketplace-sa-test",
      "private_key_id": "<GOOGLE_PRIVATE_KEY_ID>",
      "private_key": "<GOOGLE_PRIVATE_KEY>",
      "client_email": "[email protected]"
    }
  }'

{
  "request_id": "1",
  "data": {
    "id": "<NYLAS_CONNECTOR_CREDENTIAL_ID>",
    "credential_type": "serviceaccount",
    "name": "Test Google service account credential",
    "created_at": 1656082371,
    "updated_at": 1656082371
  }
}

Save the id from the response. You’ll use this credential_id when creating grants.

Step 3: Create a Google bulk auth grant

Make a Custom Authentication request to create a grant for a specific user’s email address. Use the credential_id from the previous step.

curl --request POST \
  --url 'https://api.us.nylas.com/v3/connect/custom' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json, application/gzip' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>' \
  --data '{
    "provider": "google",
    "settings": {
      "credential_id": "<NYLAS_CONNECTOR_CREDENTIAL_ID>",
      "email_address": "[email protected]",
      "scopes": ["https://www.googleapis.com/auth/gmail.readonly"]
    }
  }'

{
  "request_id": "171cac55-10b6-4989-9e03-8f4a9795ca61",
  "data": {
    "id": "<NYLAS_GRANT_ID>",
    "grant_status": "valid",
    "provider": "google",
    "scope": [
      "openid",
      "https://www.googleapis.com/auth/userinfo.email",
      "https://www.googleapis.com/auth/userinfo.profile",
      "https://www.googleapis.com/auth/gmail.readonly"
    ],
    "email": "[email protected]",
    "settings": {
      "app_permission": true,
      "credential_id": "6c40d1e8-b1b4-4a58-a92a-93a34b666a0f",
      "credential_type": "serviceaccount",
      "scopes": ["https://www.googleapis.com/auth/gmail.readonly"]
    },
    "ip": "<IP_ADDRESS>",
    "user_agent": "sensitive_data",
    "created_at": 1749053226,
    "updated_at": 1749053226,
    "provider_user_id": "[email protected]",
    "blocked": false
  }
}

Repeat this step for each user you want to authenticate. Because the service account has domain-wide delegation, you can create grants for any user in the Google Workspace domain.

Create Microsoft bulk authentication grants

Microsoft bulk auth grants use Azure AD admin consent to grant your app application-level permissions. Unlike Google (where you generate a service account key), you use your existing Azure app’s client ID and secret. A Microsoft admin at your customer’s organization then approves your app for their tenant, which gives it access to user mailboxes and calendars without individual OAuth flows.

Configure your Azure app for application permissions.
Register your Azure app credentials with Nylas.
Get admin consent for your app.
Create a grant for a user.

Step 1: Configure your Azure app for application permissions

If you already have an Azure app from setting up your Microsoft connector, you just need to add application permissions. If you don’t have one yet, create an Azure auth app first, then configure it:

From the Authentication tab, click Add a platform.
Set the Platform to Web and enter the Custom Auth URI.
In the Certificates & secrets tab, click New client secret and add a client secret.
Save the client secret somewhere secure, like a secrets manager. The Azure Dashboard shows the client_secret value only once. If you lose it, you’ll need to create a new one.
In the API permissions tab, click Add a permission and select Microsoft Graph from the list of APIs.
Select Application permissions and add all the Microsoft Graph scopes that your project needs, including User.Read.All.

You don’t need to select Grant admin consent here. You’ll grant consent in Step 3 using an authorization request.

Step 2: Register your Azure app credentials with Nylas

Make a Create Credential request to register your Azure app’s client_id and client_secret with Nylas. You don’t need to generate any new credentials for this step — use the client ID and secret from your existing Azure app.

curl --request POST \
  --url 'https://api.us.nylas.com/v3/connectors/microsoft/creds' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json, application/gzip' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>' \
  --data '{
    "name": "Test Microsoft credential",
    "credential_type": "adminconsent",
    "credential_data": {
      "client_id": "<MICROSOFT_CLIENT_ID>",
      "client_secret": "<MICROSOFT_CLIENT_SECRET>",
      "tenant": "<MICROSOFT_TENANT>"
    }
  }'

{
  "request_id": "1",
  "data": {
    "id": "<NYLAS_CONNECTOR_CREDENTIAL_ID>",
    "credential_type": "adminconsent",
    "name": "Test Microsoft credential",
    "created_at": 1656082371,
    "updated_at": 1656082371
  }
}

Save the id from the response. You’ll use this credential_id in the next steps.

The tenant field controls which organizations can use the admin consent URL:

common — the consent URL works for any Microsoft organization. Your app gets the scopes configured in your Azure app’s API permissions.
A specific tenant ID — the consent URL only works for that organization, but you can override scopes in the URL itself.

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

Send the following OAuth Authorization URL to the Microsoft admin at your customer’s organization. When they open it, Microsoft prompts them to approve your app’s application-level permissions for their tenant. Use the credential_id from the previous step.

If you set tenant to common (scopes come from your Azure app’s API permissions):

https://api.us.nylas.com/v3/connect/auth?
provider=microsoft&
redirect_uri=<REDIRECT_URI>&
response_type=adminconsent&
state=<STATE>&
credential_id=<NYLAS_CONNECTOR_CREDENTIAL_ID>&
client_id=<NYLAS_CLIENT_ID>

If you specified a tenant ID (you can override scopes in the URL):

https://api.us.nylas.com/v3/connect/auth?
provider=microsoft&
redirect_uri=<REDIRECT_URI>&
response_type=adminconsent&
state=<STATE>&
credential_id=<NYLAS_CONNECTOR_CREDENTIAL_ID>&
client_id=<NYLAS_CLIENT_ID>&
scope=https%3A%2F%2Fgraph.microsoft.com%2FCalendars.Read%20https%3A%2F%2Fgraph.microsoft.com%2FCalendars.Read.Shared

After the admin approves, Nylas redirects to your redirect_uri with admin_consent=true and the state parameter. If the flow fails, Nylas returns an OAuth 2.0 error with state, error, error_description, and error_uri.

Wait at least 5 minutes after admin consent before creating a grant. Microsoft caches scopes and needs time to propagate the updated permissions.

Step 4: Create a Microsoft bulk auth grant

Make a Custom Authentication request to create a grant for a specific user’s email address.

curl --request POST \
  --url 'https://api.us.nylas.com/v3/connect/custom' \
  --header 'Accept: application/json, application/gzip' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "provider": "microsoft",
    "settings": {
      "credential_id": "<NYLAS_CONNECTOR_CREDENTIAL_ID>",
      "email_address": "[email protected]"
    }
  }'

{
  "request_id": "251cac55-10b6-4989-9e03-8f4a9795ca61",
  "data": {
    "id": "<NYLAS_GRANT_ID>",
    "grant_status": "valid",
    "provider": "microsoft",
    "scope": [
      "Directory.Read.All",
      "User.Read.All",
      "Mail.Read",
      "AccessReview.Read.All",
      "Application.Read.All",
      "Mail.ReadWrite",
      "Calendars.Read",
      "AccessReview.ReadWrite.All",
      "Calendars.ReadWrite",
      "Mail.Send"
    ],
    "email": "[email protected]",
    "settings": {
      "app_permission": true,
      "app_permission_scopes": [
        "Directory.Read.All",
        "User.Read.All",
        "Mail.Read",
        "AccessReview.Read.All",
        "Application.Read.All",
        "Mail.ReadWrite",
        "Calendars.Read",
        "AccessReview.ReadWrite.All",
        "Calendars.ReadWrite",
        "Mail.Send"
      ],
      "credential_id": "50f7fb25-8af7-49be-a35b-94e1d07c842b",
      "credential_type": "adminconsent"
    },
    "ip": "<IP_ADDRESS>",
    "user_agent": "sensitive_data",
    "created_at": 1749053636,
    "updated_at": 1749053636,
    "provider_user_id": "[email protected]",
    "blocked": false
  }
}

Repeat this step for each user you want to authenticate. The admin consent you obtained in the previous step covers all users in the tenant.

Create Credential — register provider credentials with Nylas
List Credentials — view credentials for a connector
Custom Authentication — create a grant using registered credentials
OAuth Authorization — generate the admin consent URL for Microsoft
List Grants — view grants associated with your application