Nylas Hosted Auth is the quickest and easiest way to setup user authentication for your app. Simply redirect users to a Nylas login page and we'll handle the rest including auto-detection of third party providers and managing token exchanges.

📘

Looking to authenticate an account for development or testing?

If all you need is an account access token so you can test Nylas or start developing with Nylas, we make it easy to authenticate accounts through the Nylas Dashboard. Take a look at our guide to get your API keys for details.

Here's the process:

1. Redirect your user to the Nylas Hosted Auth service, and include query parameters that specify scopes, a redirect URL, and the authorization flow (code or token).
2. The user logs into their account and consents to the permissions your app requests. Then, Nylas redirects them back to your app and provide the appropriate authorization credentials.
3. Your app takes the appropriate steps to receive an access token for the account from Nylas and begins using it to make requests to Nylas on behalf of the user.

Prerequisites: Add the Redirect URI

The callback URI or redirect_uri is used to redirect the user back to your application after authentication. Add the redirect_uri in the dashboard Application > Application Settings > Callback URI.

Step 1: Redirect the User to the Nylas Hosted Auth Service

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 -G \
  --url 'https://api.nylas.com/oauth/authorize' \
  -H 'Authorization: Basic ENCODED_CLIENT_SECRET' \
  -d 'client_id=nylas_client_id' \
  -d 'redirect_uri=http://example.com/nylas_callback' \
  -d 'response_type=code' \
  -d 'scopes=email.read_only,calendar.read_only,contacts.read_only' \
  -d '[email protected]' \
  -d 'state=MyCustomStateString'
  
# After your user authenticates, Nylas will return a unique, one-time-use code.
# This code can be used to create an access token that grants access to the user account.
# See: https://docs.nylas.com/reference#oauthtoken

from nylas import APIClient

nylas = APIClient(
    CLIENT_ID,
    CLIENT_SECRET
)
auth_url = nylas.authentication_url(
    "http://example.com/login_callback", # Required
    login_hint="[email protected]",  # Optional
    state="unique_identifier",  # Optional
    scopes='email, calendar, contacts' # Optional - Default is all scopes
    # A full list of available scopes can be found here:
    # https://docs.nylas.com/docs/authentication-scopes
)

# This is the URL you need to send the user to to authenticate their account.
print(auth_url)

# After your user authenticates, Nylas will return a unique, one-time-use code.
# This code can be used to create an access token that grants access to the user account.
# See: https://docs.nylas.com/reference#oauthtoken

const Nylas = require('nylas');

Nylas.config({
  clientId: CLIENT_ID,
  clientSecret: CLIENT_SECRET,
});

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

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

📘

Scopes parameter name

If you're experiencing issues getting the desired scopes list, please double-check that your URL parameter is named scopes, as shown in the example, rather than scope.

Step 2: User Consent

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: Handle the User Redirect and Auth Credentials

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.

📘

Custom URL Schemes

If you're building a mobile app or desktop application, you may want to use a custom URL scheme to listen for the redirect to happen in the user's web browser. For example, myapp://app/auth-response.

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 begin 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 log in 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.