Version:
Only show these results:

Bulk authentication grants and Service Accounts

A bulk authentication grant (also called a "Service Account") is a special type of grant used by a Nylas application or a compute workload, rather than a user. Nylas applications can use bulk auth grants to make authorized API calls instead of requiring an admin user.

ℹ️ 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.

Use Microsoft bulk authentication grants

Nylas supports Microsoft bulk auth grants and the Microsoft Admin Consent flow.

Set up Azure authentication application

To use a Microsoft bulk auth grant with your Nylas application, you first need to create an Azure auth app and configure it as follows:

  1. From the Authentication tab, click Add a platform. Set the Platform to Web and enter the Nylas redirect URI.
    • Hosted Auth: Enter https://api.us.nylas.com/v3/connect/callback (U.S.) or https://api.eu.nylas.com/v3/connect/callback (E.U.).
    • Custom Auth: Enter your project's callback URI.
  2. 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. For best practices, see Storing secrets securely.

  3. In the API permissions tab, click Add a permission and select Microsoft Graph from the list of APIs.
  4. 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 a special Nylas authorization API request.

Your Nylas application also needs to have a working Microsoft connector.

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.

curl --request POST \
  --url 'https://api.us.nylas.com/v3/connectors/<CONNECTOR>/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
  }
}

🔍 You can set the tenant to common in your bulk auth requests instead of creating custom admin consent URLs for each of your customers. If you do this, however, you can't specify scopes in the admin consent URL — Nylas uses the scopes set by your Azure auth app. 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 instead of specifying common.

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

Create Microsoft bulk authentication grant

First, make an OAuth Authorization request to request administrator approval for the scopes that you requested when you created your Azure auth app.

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>   
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

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.

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": "nyla@example.com"
      }
    }'   
{
  "request_id": "1",
  "data": {
    "id": "<NYLAS_GRANT_ID>",
    "provider": "microsoft",
    "grant_status": "valid",
    "email": "nyla@example.com",
    "scope": [
      "Calendars.Read",
      "Calendars.Read.Shared"
    ],
    "user_agent": "<USER_AGENT>",
    "settings": {},
    "ip": "<IP_ADDRESS>",
    "state": "<STATE>",
    "created_at": 1617817109,
    "updated_at": 1617817109
  }
}

Google App Permission via Nylas

Before you begin, create a new provider auth application in Google Cloud Platform.

Next, make sure that the Nylas application you want to connect the bulk auth grant to has a Google connector. You can check from the Dashboard or make a GET /v3/connectors request to check. If you don't have one, create one from the Dashboard or make a POST /v3/connectors request.

  1. Create a unique Nylas connector credential for the Google account using the /v3/connectors/{provider}/creds endpoint. The request body must contain more details for Google credentials because the scopes are defined for each grant individually. Unlike Microsoft, the Google bulk auth grants do not require "admin consent".

    {
      "name": "credential Google", #REQUIRED
      "credential_type": "serviceaccount", #REQUIRED
      "credential_data": {
        "type": "service_account",
        "project_id": "marketplace-sa-test",
        "private_key_id": "private123456key", #REQUIRED
        "private_key": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n", #REQUIRED
        "client_email": "name@marketplace-sa-test.iam.gserviceaccount.com", #REQUIRED
        "client_id": "123456789123456789123",
        "auth_uri": "https://accounts.google.com/o/oauth2/auth",
        "token_uri": "https://oauth2.googleapis.com/token",
        "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
        "client_x509_cert_url": "https://www.googleapis.com/robot/v1/metadata/x509/name%40marketplace-sa-test.iam.gserviceaccount.com"
      }
    }

  2. Nylas sends a response body that looks like the example below. Save the id from the payload. This is the ID of the Nylas connector credential record you just created.

    {
      "request_id": "5967ca40-a2d8-4ee0-a0e0-6f18ace39a90",
      "data": {
        "id": "e19f8e1a-eb1c-41c0-b6a6-d2e59daf7f47",
        "integration_id": "d1n4M0ZG-ac12-13ab-98ed-1fe33cbd43a1",
        "name": "credential Google",
        "created_at": 1656082371,
        "updated_at": 1656082371
      }
    }

  3. When you have this id, you can make a POST /v3/connect/custom request to create an app permission grant.
    This is a Google bulk auth grant in the Nylas platform. The request body would look like the example below.

    {
      "provider": "google", #REQUIRED
      "settings": {
        "credential_id": "e19f8e1a-eb1c-41c0-b6a6-d2e59daf7f47", #REQUIRED
        "email_address": "alex@google.com", #REQUIRED
        "scopes" : ["https://www.googleapis.com/auth/gmail.readonly"] #REQUIRED
      }
    }
    • provider: The provider name (in this case, google).
    • credential_id: The ID of the Nylas connector credential record from the previous step.
    • email_address: The email address associated with the Microsoft account that you're creating a grant for. Nylas will make App Permission calls for this email address. If the email address is already associated with a grant, Nylas re-authenticates the grant.
    • scopes: A space-delimited list of scopes that the bulk auth grant needs. These apply only to the given account.

  4. The response payload when you create this special bulk auth grant is the same as for a normal grant creation.