Bulk authentication grants

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. A Microsoft Entra ID (formerly 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.

Bulk auth grants aren’t related to Nylas Service Accounts, which use cryptographic request signing for organization-level admin APIs.

Before you begin

Make sure 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.

When you delegate domain-wide authority, the scope list you enter in the Google Admin console must include every scope you plan to pass when you create grants in Step 3.

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' \
  --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, and list the scopes the grant needs. Each scope must appear in the service account’s domain-wide delegation list, or grant creation fails.

curl --request POST \
  --url 'https://api.us.nylas.com/v3/connect/custom' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --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 Microsoft Entra 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

Your Azure app needs a web platform, a client secret, and Microsoft Graph application permissions. If you already configured the platform and secret when setting up your Microsoft connector, skip to step 4 and add the application permissions. If you don’t have an Azure app yet, create one 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 portal 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 the Microsoft Graph permissions your project needs, including User.Read.All. To work out which ones, see Calculating scopes in the Azure app guide and the scopes reference. Only add the permissions your integration uses, because tenant admins see the full list when they grant consent.

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' \
  --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, state, and tenant_id=<azure-tenant-guid>. 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. Use the credential_id from Step 2. Unlike the Google request, you don’t pass scopes here. The grant inherits the application permissions the admin consented to.

curl --request POST \
  --url 'https://api.us.nylas.com/v3/connect/custom' \
  --header 'Accept: application/json' \
  --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": [
      "User.Read.All",
      "Mail.Read",
      "Mail.ReadWrite",
      "Mail.Send",
      "Calendars.Read",
      "Calendars.ReadWrite"
    ],
    "email": "[email protected]",
    "settings": {
      "app_permission": true,
      "app_permission_scopes": [
        "User.Read.All",
        "Mail.Read",
        "Mail.ReadWrite",
        "Mail.Send",
        "Calendars.Read",
        "Calendars.ReadWrite"
      ],
      "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
  }
}

The scope and app_permission_scopes arrays in the response mirror the application permissions the admin consented to in Azure. Nylas doesn’t require a fixed list. Your response shows whichever Graph permissions you configured on your Azure app, so it might differ from this example.

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