Only show these results:
private-preview

Create a Microsoft Teams integration

This feature is a private preview release and should be used with caution. Its features and implementation will likely change before it is generally available.

You can connect your accounts to Microsoft Teams and make adding Teams details to events much simpler. Configure events defaults in Teams, then add meetings by adding Teams to the event details.

Get started

To connect Nylas with Microsoft Teams:

  1. Create an Azure app (or use an existing one) so you can connect to Microsoft.
  2. Create a Teams integration with Nylas, and authenticate.
  3. Create calendar events with Teams!

Create or re-use an Azure app

To integrate with Microsoft Teams, you need an Azure app. If you already have an Azure app, follow all of the steps below.

If you don't yet have an Azure app, or if you want to create a new one, follow the steps in creating an Azure app, then return to this page to complete the rest of the steps.

Upgrade to Graph

The steps below cover the process of upgrading to Graph.

Add relevant Graph scopes

In the Azure app, add the Graph scopes that you are using for your Nylas integration.

  1. From the Azure portal home page, search for and click App Registrations.
  2. Click on the application you want to configure.
  3. On the left, click API Permissions.
  4. Click Add a permission.
  5. Click Microsoft Graph.
  6. Depending on the Nylas features you are using, add the permissions below:
    • Email Messages Read only | Mail.Read
    • Email Messages Read and Write | Mail.ReadWrite
    • Email Send | Mail.ReadWrite and Mail.Send
    • Calendar Read and Write | Calendar.ReadWrite
    • Contacts Read only | Contacts.Read
    • Contacts Read and Write | Contacts.ReadWrite

Keep the existing EWS and EAS scopes

Nylas is migrating services over to Microsoft Graph in phases. Your integration might experience interruptions if you remove Exchange Web Service (EWS) or Exchange ActiveSync (EAS) scopes. You'll receive an update from Nylas when you can remove these scopes.

Microsoft Azure Portal displaying the API Permissions page.

Re-authenticate users

You must re-authenticate users to add the new Graph scopes for Nylas. This process switches you to using Graph for your integration. Re-authentication is required for the changes to take effect. To complete this, you'll need to do one of the following:

  • Force re-authentication for your users.
  • Ask your users for them to re-authenticate.

Once your users have granted Nylas the Graph scopes, you can continue setting up the Teams integration.

Add the Graph permission to your Azure app

Add the Graph permission OnlineMeetings.ReadWrite to your Azure app. If you're adding this permission to an existing app, your users must re-authenticate for it to take effect.

  1. From within your app in the Azure portal, click on API permissions.
  2. Click on Add a permission.
  3. Click Microsoft Graph.
  4. Click Delegated permissions.
  5. Use the search bar to find OnlineMeetings.ReadWrite.

Add redirect URIs to the Azure app

  1. From within your app in the Azure portal, click Authentication.
  2. Click Add a platform.
  3. Click Web.
  4. The URI is required to complete the authentication flow. The URI you'll add depends on your location:
    • If you're in the United States, use https://beta.us.nylas.com/connect/callback
    • If you're in Europe, use https://beta.eu.nylas.com/connect/callback
  5. Click Configure.
  6. Scroll down to the Implicit grant and hybrid flows heading and check both boxes:
    • Access tokens (used for implicit flows)
    • ID tokens (used for implicit and hybrid flows)
  7. Click Save.
  8. Scroll down to the Supported account types heading, and choose which type of application you're using.
    Use single tenant if you need to limit authentication to accounts from your specific organization, otherwise choose Multitenant. If you select Single tenant you need your tenant ID from the Overview page, and you must MDM verify your app before you can publish it.
  9. Click Save.

Get the client secret and value from the Azure app

If you already have your client secret and value, then you can skip this section.

  1. From within your app in the Azure portal, click Certificates & secrets.
  2. Click New client secret.
  3. Fill in the description field and select the duration you'd like it to be valid.
  4. Copy the value and keep it somewhere safe. You'll need it in the next step.

Create a Teams integration

In this step, you create a Microsoft Teams integration with Nylas.

You'll need to repeat the process for each account you want to connect.

Prerequisites

If you're just joining this doc, before you continue you need:

  • An Azure App with Graph scopes, and the client ID and secret for that Azure app.
  • A Nylas authenticated account. Follow the hosted or native authentication guides to authenticate a Nylas account.

Use the correct base URL based on your location:

  • If you're in the United States, use https://beta.us.nylas.com
  • If you're in Europe, use https://beta.eu.nylas.com

To set up the integration:

  1. Convert your Nylas client ID and client secret to Base64
  2. Make a POST request to connect/integrations

Prepare to authenticate the requests

To authenticate the request, use your Base64 encoded <NYLAS_CLIENT_ID:NYLAS_CLIENT_SECRET> for basic authentication. You can use Shell or Bash to convert to base64 encoded. The command for shell is shown below:

echo ‘d57963d558d1:b35592e51016’ | base64
4oCYZDU3OTYzZDU1OGQxOmIzNTU5MmU1MTAxNuKAmQo=

Make sure to put a colon between NYLAS_CLIENT_ID and NYLAS_CLIENT_SECRET in your command.

Make a POST request to connect/integrations

In this step, you’ll associate the Teams integration with your Nylas application.

There are two options: Single tenant and Multitenant.

Single Tenant

Single tenant requires you to pass in the tenant ID. You can find this on the Azure app's overview page.

Parameter Type Description
name string The name of the integration.
provider string The provider name (in this case, microsoft).
settings.client_id string Your Azure auth app's client ID.
settings.client_secret string Your Azure auth app's client secret.
settings.tenant string For single tenant, always tenant_ID.
redirect_uris array An array containing a list of redirect URIs. You can include multiple URIs, but at least one must match the Redirect URL for OAuth listed in your Azure auth app.
expires_in string The expiration date of the issued JWT. Defaults to 14 days (1,209,600 seconds).
curl --location --request POST 'https://beta.us.nylas.com/connect/integrations' \
--header 'Authorization: Basic <NYLAS_CLIENT_ID:NYLAS_CLIENT_SECRET>' \
--header 'Content-Type: application/json' \
--data-raw '{
"name": "Teams Test app",
"provider": "microsoft",
"settings":
{
"client_id": "<AZURE_CLIENT_ID>",
"client_secret": "<AZURE_CLIENT_SECRET>",
"tenant": "<TENANT_ID>"
},
"redirect_uris": [
"https://myapp.com/callback-handler"
],
"expires_in": 1209600
}'

Response Single tenant

{
"success": true,
"data": {
"id": "3d6d9d51-2269-434d-85b8-73d44bb86e24",
"name": "Teams Test app",
"provider": "microsoft",
"redirect_uris": [
"https://myapp.com/callback-handler"
],
"expires_in": 1209600
}
}

Multitenant

Multitenant requires that you pass in common as the tenant value.

Parameter Type Description
name string The name of the integration.
provider string The provider name (in this case, microsoft).
settings.client_id string Your Azure auth app's client ID.
settings.client_secret string Your Azure auth app's client secret.
settings.tenant string For multitenant, always common.
redirect_uris array An array containing a list of redirect URIs. You can include multiple URIs, but at least one must match the Redirect URL for OAuth listed in your Azure auth app.
expires_in string The expiration date of the issued JWT. Defaults to 14 days (1,209,600 seconds).
curl --location --request POST 'https://beta.us.nylas.com/connect/integrations' \
--header 'Authorization: Basic <NYLAS_CLIENT_ID:NYLAS_CLIENT_SECRET>' \
--header 'Content-Type: application/json' \
--data-raw '{
"name": "Teams Test app",
"provider": "microsoft",
"settings":
{
"client_id": "<AZURE_CLIENT_ID>",
"client_secret": "<AZURE_CLIENT_SECRET>",
"tenant": "common"
},
"redirect_uris": [
"https://myapp.com/callback-handler"
],
"expires_in": 1209600
}'

Response Multitenant

{
"success": true,
"data": {
"id": "3d6d9d51-2269-434d-85b8-73d44bb86e24",
"name": "Teams Test app",
"provider": "microsoft",
"redirect_uris": [
"https://myapp.com/callback-handler"
],
"expires_in": 1209600
}
}

Create a Teams authentication request

Now that you have a Microsoft integration, you’ll need to grant account access to Microsoft.

In this step, you pass in a Nylas account_id to associate Microsoft to the correct account. The response returns the authentication URL. Make sure to review our guide on the grant endpoint for more optional fields.

Name Type Description
provider string This is always microsoft.
redirect_uri string This needs to match the Redirect URL for OAuth in your Teams integration.
expires_in string This shows the specified expiration date of the issued JWT. The default is 14 days (1,209,600 seconds). You're able to overwrite this at the grant level.
account_id string The Nylas account_id that can use the Teams integration.
scope array of strings Set the scopes you want the account to have access to in Microsoft. This is a required field.

You’ll notice some of the fields you used for Integration are also in Grants. You can set Integration defaults and override them at the Grant level.

curl --location --request POST 'https://api.us.nylas.com/connect/auth' \
--header 'Authorization: Basic <NYLAS_CLIENT_ID:NYLAS_CLIENT_SECRET>' \
--header 'Content-Type: application/json' \
--data-raw '{
"provider": "microsoft",
"redirect_uri": "https://myapp.com/callback-handler",
"expires_in": 43200,
"account_id": "anz2nojgkfzfo4094wi291hzq",
"scope":[
"User.Read",
"offline_access",
"OnlineMeetings.ReadWrite",
"openid",
"profile",
"EAS.AccessAsUser.All",
"EWS.AccessAsUser.All"
]
}'

Response Create a Teams authentication request

{
"success": true,
"data": {
"url": "https://beta.us.nylas.com/connect/login?id=nn9Gi0sZOdbULHuVTC8XOmLKZc1ftHlAeiAa",
"id": "nn9Gi5sZOdbULHtVTC8DOmLKZc2ftHlAeiAa",
"expires_at": 1632293094,
"request": {
"provider": "microsoft",
"redirect_uri": "https://myapp.com/callback-handler",
"scope": [
"User.Read",
"offline_access",
"OnlineMeetings.ReadWrite",
"openid",
"profile",
"EAS.AccessAsUser.All",
"EWS.AccessAsUser.All"
],
"account_id": "anz2nojgkfzfo4094wi291hzq"
}
}
}

See the Hosted authentication endpoint documentation to learn more.

Redirect the user to authenticate

In the previous step, Nylas returns an authentication URL. Direct the user to that URL so they can authenticate with Teams. The user must give consent to authorize the app to create conferencing objects on their behalf.

Nylas Directs the User

Once the user authenticates, Nylas send them to the redirect URI you specified in the steps above. Nylas also includes the status of the grant, the grant_id, and the provider encoded in the URI, as in the example below.

[email protected]&grant_id=377a3784-bc39-4a5f-8f57-cecfa97ba74c#   

Success!

At this point, the authentication is successful, and the user can start creating Teams meetings.

What's next?

FAQ

Can I autocreate a teams event and add details manually?

No, you need to either manually add the Teams event or use autocreate.

Can I customize the authentication?

Users need to authenticate against Microsoft to autocreate events. You can redirect them to a different page after authentication.