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.
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:
- 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. - 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. - From the API permissions tab, click Add a permission.
- Select Microsoft Graph from the list of APIs.
- 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.
- 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.
Prepare Nylas application for Microsoft Admin Consent flow
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:
-
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'sclient_id
andclient_secret
, and can include itstenant
.{
"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
andclient_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 theclient_id
,client_secret
, andtenant
(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.
- If you don't define the
-
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
}
}
Make a Microsoft Admin Consent flow request using Nylas APIs
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.
-
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=71dd22z6os123fgev42xnxbqhttps://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.Sharedprovider
: 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 isadminconsent
.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.
-
Nylas redirects the Service Account to the
redirect_uri
. The response URL contains theadmin_consent:true
and the contents of thestate
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
, anderror_uri
.
- If the flow is not successful, Nylas returns a normal OAuth 2.0 error which includes the
-
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.
-
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.
-
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"
}
} -
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
}
} -
When you have this
id
, you can make aPOST /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.
-
The response payload when you create this special bulk auth grant is the same as for a normal grant creation.