public-beta-v3

Bulk authentication in v3

The Nylas API v3 is in public beta. It might contain bugs, and might change before it is generally available. See the v3 Beta documentation for more information.

A bulk authentication grant (sometimes just "bulk auth grant") is a special kind of account used by an application or compute workload rather than a person. These are sometimes called Service Accounts.

Nylas applications can use bulk auth grants to make authorized API calls instead of requiring an admin user.

More info about Service Accounts can be found in the official Google Service Accounts documentation and Microsoft Service Accounts documentation.

Microsoft Bulk auth grants in Nylas

First create new Microsoft Azure auth application. Open the application in the Microsoft Azure dashboard and configure it with the settings described below.

Azure application set up:

From the Authentication tab, add a new platform and set its redirect URI.
For example, choose web platform, and enter Nylas's callback API as the redirect URI:https://api.us.nylas.com/connect/callback.
Click Certificates & secrets, and create a new client_secret. Save the secret value somewhere secure, as it will only be shown once. If you lose this secret, you will have to create a new one.
In the API permissions section, add all the scopes of Microsoft Graph that your project needs access to. This gives your bulk authentication grant access as well.
You don't need to add "Grant admin consent". We'll grant this later using a special Nylas authorization API call
From the Owners tab add the admin user who will grant admin consent after the Nylas special authorization API call.
From the Manifest tab set the following two values:
- "accessTokenAcceptedVersion": 2 and
- "signInAudience": "AzureADandPersonalMicrosoftAccount"

Nylas APIs

Before you start, make sure that the Nylas application you want to add the bulk auth grant to has a Microsoft connector. You can check from the Dashboard or make a call to GET /v3/integrations to check. (If you don't have a Microsoft connector, create one.)

Create a unique Nylas connector credential for the Microsoft account using the /v3/integrations/<provider>/creds endpoint.

The request body includes the original provider's client_id and client_secret. When you use a bulk auth grant that uses this credential, Nylas uses this client_id and client_secret to create the bulk auth grant.

The Microsoft credential body can only contain a name, the credential type, and the data payload, containing the client_id and client_secret.
```
{
"name": "test credential Microsoft", #REQUIRED
"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
 }
}   
```

Nylas sends a response body similar to the example below:

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

Save the id from the payload. This is the ID of the Nylas connector credential record you just created.

Call the Nylas authorization API, GET /v3/connect/auth, to request that the admin approve (or decline) the scope access you requested when you created your initial Microsoft Azure provider auth application.

The call will look like the following example.
```
https://api.us.nylas.com/connect/auth?
provider=microsoft&
redirect_uri=localhost:5000/callback&
response_type=adminconsent&
state=state1234&
credential_id=e19f8e1a-eb1c-41c0-b6a6-d2e59daf7f47&
client_id=71dd22z6os123fgev42xnxbq   
```
- provider : provider name. Since we're working with Microsoft Azure, microsoft.
- redirect_uri : the redirect URI to send the user to after authentication
- response_type : when you create a bulk auth grant, this will be adminconsent
- state: (optional) this is returned with the URL response as a security check feature
- credential_id: the id for the Nylas connector credential record you just created
- client_id: id of the Nylas application you want to connect to
If Microsoft's Admin Consent flow was successful, Nylas automatically redirects you to the redirect_uri. The response URL contains the flags admin_consent:true and (if you set one) the response the state param.
If the flow was unsuccessful Nylas returns a normal OAuth2.0 error, which includes state, error, error_description and error_uri.
After a successful authorization call, you can call POST https://api.us.nylas.com/v3/grants to create an app permission grant. This is a Microsoft App Permission account in the Nylas platform. The request body would look like the example below
```
{
  "provider": "microsoft", #REQUIRED
  "settings": {
    "credential_id": "e19f8e1a-eb1c-41c0-b6a6-d2e59daf7f47", #REQUIRED
    "email_address": "[email protected]" #REQUIRED
 }
}   
```
- provider: name of provider. for this example always microsoft
- settings: settings of this grant
  - credential_id: the credential id for the Nylas connector credential record you just created
  - email_address: email of Microsoft account to create grant for, and which Nylas makes App Permission calls for. If the email address already has a grant, Nylas automatically re-authenticates the grant.
The response payload when you create this special bulk auth grant is the same as for a normal grant creation.

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 call to GET /v3/integrations to check. (If you don't have one, create a new one.)

Create a unique Nylas connector credential for the Google account using the /v3/integrations/<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": "[email protected]", #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:

{
  "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
  }
}

Save the id from the payload. This is the ID of the Nylas connector credential record you just created.

Once you have this id, you can call POST https://api.us.nylas.com/v3/grants 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": "[email protected]", #REQUIRED
   "scopes" : ["https://www.googleapis.com/auth/gmail.readonly"] #REQUIRED
   }
}   
```
Where the params are as follows:
- provider: name of provider. for this example always google
- settings: settings of this grant
  - credential_id: the credential id for the Nylas connector credential record you just created
  - email_address: email of Google account to create grant for, and which Nylas makes App Permission calls for. If the email address already has a grant, Nylas automatically re-authenticates the grant.
  - scopes: space delimited list of scopes this bulk auth grant needs, only for given email address' account.
The response payload when you create this special bulk auth grant is the same as for a normal grant creation.