Integrations Hosted Authentication

These steps go over the general authentication process for Integrations. Each provider will have it's own requirements. Review the provider documentation for details.

Prerequisites

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

Integration Steps Overview

Depending on the provider, the following steps can vary. Review the provider documentation for detailed step-by-step instructions.

You'll send a POST request to /connect/integrations with the base64 encoded client ID and secret from your Nylas application. You'll need to include your provider information and redirect URIs.
1. In the response, Nylas will return the integration information.
Then you'll grant account access to your integration by passing in the Nylas account information.
1. In the response, Nylas will return the authentication URL for the account.
You'll want to redirect users to the authentication URL returned.
Once authenticated, the user is then redirected back to the redirect URI specified, and the browser URL will have the provider name and grant ID.
1. If authentication fails, it will return false and the event code.
At this point, authentication is successful, and the user can start using the integration.

Step 1 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 have your Integration created, you only have 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, you can update your Integration.

The redirect_uri is where the user will be sent after they have completed authentication.

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
}

Step 2 Create a Hosted Authentication Request

This is where you will authenticate the account. In the request, include one of the redirect_uris from Step 1. Otherwise, the request will fail. You can also create metadata to store aganist the Grant object.

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"
        }
    }
}

Step 3 Redirect the User

As part of the response to , you'll get a unique login URL. For example, https://beta.us.nylas.com/connect/login?id=BA630DED06 The login URL is only valid for a short amount of time and can only be used once.

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

Step 4 Provider Redirect

After authentication, the provider will direct the user to the provided redirect_uri from Step 1.

Once the end user gets 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 requested using /connect/auth with the query params:

success
grant_id
provider
email

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

Step 5 Authentication Complete

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

What's Next?

Zoom