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 an end user. Nylas applications can use bulk auth grants to make authorized API calls, instead of requiring an admin user.

Nylas v3 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.

ℹ️ Bulk authentication is available for Plus plans only.

Use a Microsoft bulk authentication grant

To use a Microsoft bulk auth grant with your Nylas application, you must first create an Azure auth app. Then, open the application in the Microsoft Azure Dashboard and configure it as follows:

  1. From the Authentication tab, click Add a platform and set the redirect URI.
    For example, select a web platform and enter Nylas' callback API, https://api.us.nylas.com/v3/connect/callback, as the redirect URI.
  2. From the Certificates & secrets tab, click New client secret and add a client secret.

    ⚠️ Be sure to save the client secret value somewhere secure. The Microsoft Azure Dashboard shows the client client_secret value only once. If you lose the it, you must create a new one.

  3. From the API permissions tab, click Add a permission.
  4. Select Microsoft Graph from the list of APIs.
  5. Select Application permissions and add all Microsoft Graph scopes that your project needs access to. This gives your bulk auth grant the access it requires.
    • You don't need to select Grant admin consent. You add this later using a special Nylas authorization API call.
  6. On the Manifest tab, add the following key/value pairs:
    • "accessTokenAcceptedVersion": 2
    • "signInAudience": "AzureADandPersonalMicrosoftAccount"

Nylas v3 supports two versions of Microsoft's Service Accounts:

  • Version 1.0: This is the older version, where every scope defined in your Azure app is requested during the authorization step of the Admin Consent flow. For this version, the tenant definition is optional (Nylas uses "tenant": "common" if you don't define it).
  • Version 2.0: This is the new version, where scopes are defined for the Admin Consent flow. This allows you the option to specify certain scopes that are used for the Admin Consent flow only. All requested scopes must still be defined in your Azure app. For this version, you must specify the exact Microsoft Azure tenant (v2.0 does not support "tenant": "common").

Nylas determines which version of the Microsoft Admin Consent flow to use based on input parameters that are passed to Nylas' Microsoft Admin Consent flow endpoint.

Before you begin, make sure that your Nylas application has a Microsoft connector set up. You can do this from the Nylas Dashboard, or by making a GET /v3/connectors request. If your application doesn't have a Microsoft connector, follow the instructions in Add Microsoft connector to Nylas.

Next, follow these steps to prepare your Nylas application for the Microsoft Admin Consent flow:

  1. Create a unique Nylas connector credential for your Microsoft grant using the /v3/connectors/{provider}/creds endpoint. The request body must include the original provider's client_id and client_secret, and can include its tenant.

    {
      "name": "Test Microsoft credential", #REQUIRED, user-defined name
      "credential_type": "adminconsent" #REQUIRED
      "credential_data": {
        "client_id": "abcd1234-abcd-1234-b558-abcd1234", #REQUIRED, PROVIDER ORIGINAL
        "client_secret": "lsu2Ek~R2swQDSe_Cx3NuLrI7wBXxZn~hyt6MLLO", #REQUIRED, PROVIDER ORIGINAL
        "tenant": "defg5678-defg-5678-b558-defg5678", #OPTIONAL, PROVIDER ORIGINAL (required for Admin Consent flow v2.0)
      }
    }
    • If you don't define the client_id and client_secret in the body of the request, Nylas uses the credentials associated with your application's Microsoft connector.
    • The Microsoft credential body can contain only the name, credential_type, and the data payload, which includes the client_id, client_secret, and tenant (if defined).
    • If you define the tenant field in the credential's payload body, Nylas attempts to use Microsoft's Admin Consent flow v2.0.

  2. Nylas sends a JSON response similar to the following example. The id parameter is the ID of the Nylas connector credential record that you just created — be sure to save it for later.

    {
      "request_id": "5967ca40-a2d8-4ee0-a0e0-6f18ace39a90",
      "data": {
        "id": "e19f8e1a-eb1c-41c0-b6a6-d2e59daf7f47",
        "credential_type": "adminconsent",
        "name": "test credential Microsoft",
        "created_at": 1656082371,
        "updated_at": 1656082371
      }
    }

After you have your Nylas application set up to use the Microsoft Admin Consent flow, you can make a request using the Nylas APIs.

🔍 Based on how you defined your Microsoft credential, Nylas determines which version of the Admin Consent flow to call (version 1.0 or 2.0). For more information, see Use a Microsoft bulk authentication grant.

  1. Make a GET /v3/connect/auth call to request that the administrator approves or declines the scopes you requested when you created your Microsoft Azure provider auth app.

    https://api.us.nylas.com/v3/connect/auth?
    provider=microsoft&
    redirect_uri=localhost:5000/callback&
    response_type=adminconsent&
    state=state1234&
    credential_id=e19f8e1a-eb1c-41c0-b6a6-d2e59daf7f47&
    client_id=71dd22z6os123fgev42xnxbq   
    https://api.us.nylas.com/v3/connect/auth?
    provider=microsoft&
    redirect_uri=localhost:5000/callback&
    response_type=adminconsent&
    state=state1234&
    credential_id=e19f8e1a-eb1c-41c0-b6a6-d2e59daf7f47&
    client_id=71dd22z6os123fgev42xnxbq&
    scope=https%3A%2F%2Fgraph.microsoft.com%2FCalendars.Read%20https%3A%2F%2Fgraph.microsoft.com%2FCalendars.Read.Shared
    • provider: The provider name (in this case, microsoft).
    • redirect_uri: The URL where the Service Account is directed after authentication.
    • response_type: For bulk auth grants, this is adminconsent.
    • state: (Optional) Returned with the URL response as a security check feature.
    • credential_id: The ID of the Nylas connector credential record that you created (see Prepare Nylas application for Microsoft Admin Consent flow).
    • client_id: The ID of the Nylas application that you want to connect to.
    • scope: (Microsoft Admin Consent flow v2.0 only) The scopes that you're requesting for the Admin Consent flow.

  2. Nylas redirects the Service Account to the redirect_uri. The response URL contains the admin_consent:true and the contents of the state parameter (if you set one).

    • If the flow is not successful, Nylas returns a normal OAuth 2.0 error which includes the state, error, error_description, and error_uri.

  3. Make a POST /v3/connect/custom request to create an application permission grant. This is a Microsoft App Permission account within the Nylas platform.

    {
      "provider": "microsoft", #REQUIRED
      "settings": {
        "credential_id": "e19f8e1a-eb1c-41c0-b6a6-d2e59daf7f47", #REQUIRED
        "email_address": "user@example.com" #REQUIRED
      }
    }
    • provider: The provider name (in this case, microsoft).
    • credential_id: The ID of the Nylas connector credential record that you created (see Prepare Nylas application for Microsoft Admin Consent flow).
    • 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.

  4. Nylas returns a JSON response containing the new grant's information (see the Custom Authentication reference documentation for an example response).

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.