Only show these results:

Integrations

Integrations let you add additional functionality to your Nylas accounts by connecting to services such as Microsoft and Zoom.

Base URL

The base URLs for integrations are:

  • For US users - https://beta.us.nylas.com
  • For EU users - https://beta.eu.nylas.com

Keep in mind that this is only for the Integrations and Grants endpoints. Other endpoints still use api.nylas.com.

Callback URL for Beta

Add the beta callback URL to the provider app or provider during the setup process:

  • United States - https://beta.us.nylas.com/connect/callback
  • EU - https://beta.eu.nylas.com/connect/callback

Authentication

Integrations use basic authentication for all requests.

Terms to Keep in Mind

  • Integration - The provider you want to connect to the Nylas platform, such as Zoom or Microsoft.
  • Grant - The account that was authenticated against the integration. For example, after creating an integration with Google, you'll then authenticate your account with Google. Nylas will then return a Grant ID.
  • Metadata - A key:value you can pass in when creating your grant during the Hosted Authentication step. Use metadata to store account information that you can query later.

Scopes

You can set scopes for the Integrations and Grants. Scopes behave differently depending on how they are set.

Integration Scopes

Scopes are optional for Integrations. If you set scopes for the Integration, accounts (grants) authenticated without scopes inherit the Integration scopes.

Grant Scopes

Scopes are required for some Grants. If you set scopes for a Grant, it'll override the Integration scopes. You can have one Integration, and each Grant in the Integration can have different scopes.

Integrations

This is the provider you want to connect to the Nylas platform. You only need to create an Integration once. If you try to create more than one integration per application, the API will return an error.

Get a List of Integrations

Use the example script below to get a list of Integrations:

curl --location --request GET 'https://beta.us.nylas.com/connect/integrations' \
--header 'Authorization: Basic <CLIENT_ID:CLIENT_SECRET>'

Response - Get a List of Integrations

{
"data": [
{
"name": "Teams Test app",
"provider": "microsoft",
"settings": {
"client_id": "772e4abc-114f-43a3-ad03-6b138aafd7b0",
"tenant": "common"
},
"redirect_uris": [
"https://myapp.com/callback-handler"
],
"expires_in": 1209600
},
{
"name": "Zoom Test app",
"provider": "zoom",
"settings": {
"client_id": "yF7kCFLaQSGt35o4Seu7mw"
},
"redirect_uris": [
"https://myapp.com/callback-handler"
],
"expires_in": 1209600
}
],
"limit": 10,
"offset": 0
}

Create an Integration

Use the example script below to create an Integration:

curl --location --request POST 'https://beta.us.nylas.com/connect/integrations' \
--header 'Authorization: Basic <CLIENT_ID:CLIENT_SECRET>' \
--header 'Content-Type: application/json' \
--data-raw '{
"name": "Teams Test app",
"provider": "zoom",
"settings": {
"client_id": "<PROVIDER_CLIENT_ID>",
"client_secret": "<PROVIDER_CLIENT_SECRET>"
},
"redirect_uris": [
"https://myapp.com/callback-handler"

],
"expires_in": 1209600
}'

Response - Create an Integration

{
"success": true,
"data": {
"id": "cd12fd1e-cd05-4a70-8ff6-4a59fe9338bd",
"name": "Teams Test app",
"provider": "microsoft",
"redirect_uris": [
"https://myapp.com/callback-handler"
],
"expires_in": 1209600
}
}

Learn More

For more information, check out the Integrations documentation.

Grants

Grants are the account that's authenticated against the integration. For example, you grant an account permission to use Zoom. You can delete a grant (revoke access) or update the existing grant. If you change the scopes, the user must re-authenticate.

Get a List of Grants

Use the example script below to get a list of Grants:

curl --location --request GET 'https://beta.us.nylas.com/connect/grants?limit=10&provider=zoom' \
--header 'Authorization: Basic <NYLAS_CLIENT_ID:CLIENT_SECRET>'

Response - List of Grants

Use the example script below to get a list of all accounts granted access to the Zoom integration:

{
"data": [
{
"id": "e19f8e1a-eb1c-41c0-b6a6-d2e59daf7f47",
"provider": "zoom",
"grant_status": "valid",
"email": "[email protected]",
"metadata": {
"isAdmin": true,
"newsletter": true
},
"scope": [
"user:create"
],
"user_agent": "string",
"ip": "string",
"state": "my-state",
"created_at": 1617817109,
"updated_at": 1617817109
}, {
"id": "e19f8e1a-eb1c-41c0-b6a6-d2e59daf7f47",
"provider": "zoom",
"grant_status": "valid",
"email": "[email protected]",
"metadata": {
"isAdmin": true,
"newsletter": true
},
"scope": [
"user:create"
],
"user_agent": "string",
"ip": "string",
"state": "my-state",
"created_at": 1617817109,
"updated_at": 1617817109
}
],

"limit": 10,
"offset": 0
}

Update a Grant

You can update a grant's scope and provider settings. Users need to re-authenticate if permissions are changed. For more details, check the API documentation for each provider.

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

curl --location --request PATCH 'https://beta.us.nylas.com/connect/grants/<GRANT_ID>' \
--header 'Authorization: Basic <CLIENT_ID:CLIENT_SECRET>' \
--header 'Content-Type: application/json' \
--data-raw '{
"settings": {
"refresh_token": "adadada..."
},
"metadata": {
"isAdmin": true,
"newsletter": true
},
"scope": [
"user:create"
]
}'

Response - Update Grant

{
"success": true,
"data": {
"id": "e19f8e1a-eb1c-41c0-b6a6-d2e59daf7f47",
"provider": "zoom",
"grant_status": "valid",
"email": "[email protected]",
"metadata": {
"isAdmin": true,
"newsletter": true
},
"scope": [
"user:create"
],
"user_agent": "string",
"ip": "string",
"state": "my-state",
"created_at": 1617817109,
"updated_at": 1617817109
}
}

Learn More

For more information, check out the Grants documentation.

FAQ

How Many Integrations Can I Create?

You can only create one integration per provider.

What Is an Integration?

An integration is the provider you want to connect to the Nylas platform. For example, Zoom.

What Is a Grant?

A grant is the account that was authenticated against the integration. For example, you grant an account permission to use Zoom.

Where Can I Add Metadata?

You can add metadata when creating a Grant and when creating an event.

What's Next?