Only show these results:

Integrations Hosted Authentication

This guide goes over the general authentication process for Integrations. Each provider has it's own requirements. Review the provider documentation for more details.

Prerequisites

Add the appropriate beta callback URL based on your location 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

Integration Steps Overview

The following steps may vary depending on the provider. Review the provider documentation for detailed step-by-step instructions.

  1. Send a POST request to /connect/integrations with the base64 encoded Client ID and Client Secret from your Nylas application. You'll need to include your provider information and redirect URIs.
    • In the response, Nylas will return the integration information.
  2. Grant account access to your integration by passing in the Nylas account information.
    • In the response, Nylas will return the authentication URL for the account.
  3. Redirect users to the authentication URL returned.
  4. Once authenticated, the user is redirected back to the redirect URI specified, and the browser URL will have the provider name and grant ID.
    • If authentication fails, it will return false, along with the event code.
  5. Authentication is now successful and the user can start using the integration.

Create an Integration

Integrations are the provider you want to connect to the Nylas platform. You only need to create an Integration once per provider and environment. Once you create your Integration, you only need to create grants for each account.

If you create a second Integration with the same provider, the API will return an error message. If you want to change your provider settings, update your Integration.

The redirect_uri is where the user will be sent after they've been authenticated.

Below is an example script 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": "<SOME_PROVIDER>",
"settings": {
"client_id": "<PROVIDER_CLIENT_ID>",
"client_secret": "<PROVIDER_CLIENT_SECRET>"
},
"scope": [
"user:create"
],
"redirect_uris": [
"https://myapp.com/callback-handler"
],
"expires_in": 1209600
}'

Response - Create an Integration

In the response, we'll return information about the integration just created.

{
"provider": "google",
"redirect_uri": "https://myapp.com/callback-handler",
"scope": [
"user:create"
],
"grant_id": "295bb5e9-c3ba-44b4-9467-11cb9867d1ce",
"metadata": {
"isAdmin": true,
"newsletter": true
},
"login_hint": "[email protected]",
"state": "my-state",
"expires_in": 43200
}

Create a Hosted Authentication Request

This is where you'll authenticate the account. In the request, include one of the redirect_uris from the Create an integration step. If you don't include one, the request will fail. You can also create metadata to store aganist the Grant object.

Below is an example script to create a hosted authentication request:

curl --location --request POST 'https://beta.us.nylas.com/connect/auth' \
--header 'Authorization: Basic <CLIENT_ID:CLIENT_SECRET>' \
--header 'Content-Type: application/json' \
--data-raw '{
"provider": "<SOME_PROVIDER>",
"redirect_uri": "https://myapp.com/callback-handler",
"expires_in": 43200,
"account_id": "<ACCOUNT_ID>"
}'

Response - Create a Hosted Authentication Request

{
"success": true,
"data": {
"url": "https://beta.us.nylas.com/connect/login?id=oF8J4kpwRzoEbm0xKuX5x4x5KRb7j7YgraMG", //
"id": "oF8J4kpwRzoEbm0xKuJMx4x5KRb7j7YgraMG",
"expires_at": 1632203403,
"request": {
"provider": "microsoft",
"redirect_uri": "https://myapp.com/callback-handler",
"account_id": "anz2nojgkfzfo4094wi291hzq"
}
}
}

Redirect the User

You'll get a unique login URL in the response, such as https://beta.us.nylas.com/connect/login?id=BA630DED06 This URL is can only be used once and is valid for a short amount of time.

Direct your user to this unique URL so that they can authenticate the account.

Provider Redirect

After authentication, the provider will direct the user to the provided redirect_uri from the first step.

Once the user is redirected to this URL by the provider, Nylas saves tokens, metadata, and creates a new grant. It then redirects back to the specified redirect_uri using /connect/auth with the following query params:

  • success
  • grant_id
  • provider
  • email

An example of this is shown below:

https://myapp.com/callback-handler?
success=true // Whether the grant was succesfully created
&grant_id=... // GUID grant identifier for your new integration
&provider=google // Provider type
&email=... // Email address (if integration/provider type and the requested scope allows)

If authentication fails, success will be set to false:

https://myapp.com/callback-handler?
success=false // Meaning the authentication failed
&error=... // Error code

Authentication is Complete

The account has been granted access to the integration and is ready for use.

What's Next?