Hosted Authentication Guide

This guide outlines how you can set up Hosted Authentication with the Nylas APIs to connect mail accounts. At this point, you should have your Nylas organization and application set up, so you're ready to authenticate an account!

Step 1

From your application, redirect users to https://api.nylas.com/oauth/authorize, with the query parameters detailed in /oauth/authorize.

You'll need to set the response_type to code if you have a server side application, or token if you have a client side or mobile app.

You'll also need to determine what permissions your application will request from users, and update the scopes query parameter accordingly. Nylas provides granular authentication scopes that empower users with control over what level of access your application has to their data.

→ See supported Authentication Scopes for details.

Here's an example of what this URL might look like once you've included all the correct query parameters:

https://api.nylas.com/oauth/authorize?login_hint=EMAIL_ADDRESS&client_id=NYLAS_CLIENT_ID&response_type=token&redirect_uri=MY_REDIRECT_URI&scopes=email.send,email.read_only&state=CSRF_TOKEN

curl --request GET
  --url 'https://api.nylas.com/oauth/authorize'
  -d 'client_id=a1b2c3d4e5f6g7h8'
  -d 'response_type=code'
  -d 'scopes=email.send,email.read_only'
  -d 'login_hint=user@gmail.com'
  -d 'redirect_uri=https://yourapp.com/nylas-redirect'
  -d 'state=MyCustomStateString'

from flask import Flask, session, request, redirect, Response
from nylas import APIClient

client = APIClient(CLIENT_ID, CLIENT_SECRET)

redirect_url = "http://0.0.0.0:8888/login_callback"

# Redirect your user to the auth_url
auth_url = client.authentication_url(
  	redirect_url, 
  	scopes='email.read_only,email.send'
	)

const Nylas = require('nylas');

Nylas.config({
  appId: CLIENT_ID,
  appSecret: CLIENT_SECRET,
});

options = {
  loginHint: 'test@nylas.com',
  redirectURI: 'https://localhost/callback',
  scopes: ['email.read_only', 'email.send'],
};

// Redirect your user to the auth_url
auth_url = Nylas.urlForAuthentication(options);

Step 2

Nylas will present your user with the correct sign in panel based on their email address. For example, a user with a Gmail address will see the Gmail “Authorize this Application” screen, while a user with a Yahoo address is shown a Yahoo sign in panel.

If Nylas cannot autodetect the user's email provider from their address, the user will see a provider selection screen first.

For Exchange users, clicking "Advanced Settings" will enable the user to enter a login name and/or Exchange server. The majority of Exchange users can log on with their email address and auto-detected server details, but some will have to enter this additional information.

Step 3

Once the user has signed in, their browser will be redirected to the redirect_uri you provided.

Client Side

If authentication was successful and you're using a response_type of token, Nylas will include the access_token parameter in the query string. That's it! We recommend storing the access_token and then removing it from the URL fragment with JavaScript. This is the token you will provide as a HTTP Basic Auth Username to make API calls on behalf of the user.

Server Side

If your authentication was successful and you're using a response_type of code, Nylas will include a code parameter in the query string.

Make an HTTP POST to https://api.nylas.com/oauth/token to exchange the code for an access_token. See /oauth/token for details. Make sure to securely store the access_token and provide it as the HTTP Basic Auth Username to make API calls on behalf of the user.

Authenticating Google Accounts

Google has strict policies that require your application to undergo Google Application verification and a security review, depending on which scopes you request from users. In order to being syncing Google accounts in production, you'll need to reach out to Nylas support so we can assist you through this verification and security review process.

You can create your own Google Project for development purposes to test Google accounts without needing to be verified or reviewed. This Google development project will have limitations on who and how many users can authenticate. See Creating a Google Project and Client ID for Development for more details.

Authenticating Office365 Accounts

There are two options for authenticating Office365 accounts with Nylas. By default, users will be able to securely login with their password through Nylas Hosted Authentication flow. You can also configure your app to support Microsoft's Office365 OAuth login page, which looks like this:

To setup Office365 OAuth with your Nylas application please see Office365 OAuth Setup with Nylas.