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 or for EU users https://beta.eu.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.
- 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
- 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 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 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 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
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?
- Review the Integrations API reference.
- Take a look at our current integrations.