Only show these results:
Private Beta

Integrations

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

Base URL

The base URL for integrations is https://beta.us.nylas.com. This is only for 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 set up process. https://beta.us.nylas.com/connect/callback

Authentication

Integrations use basic authentication for all requests.

Terms

  • Integration - The provider you want to connect to the Nylas platform. For example, Zoom and 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, and Nylas will 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, any accounts(grants) authenticated without scopes will inherit the Integration scopes.

Grant Scopes

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

Integrations

The provider you want to connect to the Nylas platform. For example, Zoom, and Microsoft. 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

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

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

Check out the documentation on Integrations.

Grants

The account that was 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. The user will need to reauthenticate if you change the scopes.

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

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@gmail.com",
"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@gmail.com",
"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 grants scope and provider settings. Users will need to reauthenticate if permissions are changed. Check the API documentation for each provider.

You’ll notice some of the fields you used for Integration are also in Grants. You can set Integration defaults but 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@gmail.com",
"metadata": {
"isAdmin": true,
"newsletter": true
},
"scope": [
"user:create"
],
"user_agent": "string",
"ip": "string",
"state": "my-state",
"created_at": 1617817109,
"updated_at": 1617817109
}
}

Learn More

Check out the documentation on Grants.

FAQ

How Many Integrations Can I Create?

You can only create one integration per provider. You are not able to create multiple integrations.

What Is an Integration?

The provider you want to connect to the Nylas platform. For example, Zoom.

What Is a Grant?

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?