Hosted authentication in Nylas v2

This guide explains how to authenticate accounts using Hosted Authentication.

Nylas hosted authentication is the quickest and easiest way to set up user authentication for your app. With hosted authentication, you redirect users to a Nylas login page and Nylas handles the rest, including detecting third party providers including SSO identity providers, and managing token exchanges.

The login process using Nylas hosted authentication has three steps:

Redirect the user to the Nylas hosted authentication service.
The user logs in to their account and approves the permission requests from your app. Nylas redirects the user back to your app and provides the appropriate authorization credentials.
Your app receives and stores a Nylas access_token for the user, and uses it to make Nylas API requests for the user.

A flow diagram showing the Nylas Hosted authentication process.

When to use hosted authentication

Use hosted authentication:

When you don't need to follow strict appearance customization, and can show the Nylas logo on the authentication page.
To create a test application with only a few users.
To decrease your development time by letting Nylas handle the authentication.

For more information on using hosted authentication with SSO, see the Microsoft Authentication Guide and Google OAuth Setup Guide.

Hosted authentication considerations

There are few things to think about before you set up hosted authentication.

Decide if you want to make a server or client-side application. This changes what type of authorization type you use.
Determine the scopes you need. Remember that if you change scopes, the user must re-authenticate.

Step 1: Redirect the user

In your application, redirect your user to the Nylas Hosted authentication service, and include query parameters that specify scopes, a redirect URL, and the authorization flow. Make a GET request to /oauth/authorize.

The query parameters are:

client_id: Your Nylas application's client ID.
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. You also need to include the same redirect_uri in your request.
response_type: There are two response types, which you learn about in Step 3.
- code: Set the response_type to code if you have a server-side application.
- token: Set the response_type to token if you have a client-side application or a mobile app.
scopes: Review Authentication Scopes to see available scopes.
- If scopes are not specified, we will add default scopes.
redirect_on_error: Defaults to false. When set to true, users are redirected to the specified redirect_uri if there is an error during authentication, with additional query parameters that provide more information.

Error and Error Description query string parameters

If users encounter errors during authentication, Nylas includes the following query string parameters with the redirect_uri you specified. You can use the error description in your app to help the user understand the error, so they can try again if it's something they can correct.

Error	Description
`unknown`	Unknown error.
`invalid_request`	The request is missing a required parameter, has an invalid parameter value, has a repeated parameter, or is otherwise malformed.
`access_denied`	The user or authorization server denied the request.
`unauthorized_client`	The client is not authorized to request an authorization code using this method.
`unsupported_response_type`	The server does not support obtaining an authorization code using this method.
`invalid_scope`	Requested Google scopes denied by end user. Please retry the authentication process and ensure you tick the boxes to enable the specific scopes.
`server_error`	The authorization server encountered an unexpected condition that prevented it from fulfilling the request.
`temporarily_unavailable`	The authorization server is currently undergoing maintenance, or is otherwise unavailable and is unable to handle the request.

Example redirect URL

The URL below shows an invalid_scope error with the description included. Line breaks separate query string parameters for visibility.

https://example.com/nylas_callback?
error=invalid_scope&
error_description=Requested Google scopes denied by end user. Please retry the authentication process and ensure you tick the boxes to enable the specific scopes.

Example `/oauth/authorize` request

This provided as an example. Users will need to log in on the webpage.

curl -G \
  --url 'https://api.nylas.com/oauth/authorize' \
  -H 'Authorization: Basic ENCODED_CLIENT_SECRET' \
  -d 'client_id=nylas_client_id' \
  -d 'redirect_uri=https://example.com/nylas_callback' \
  -d 'response_type=code' \
  -d 'scopes=email.read_only,calendar.read_only,contacts.read_only' \
  -d 'login_hint=my_email@example.com' \
  -d 'state=MyCustomStateString' \
  -d `redirect_on_error=true`

Once you make this API request, your users will be asked to consent to the authentication scopes listed in the request.

Learn More

A full list of query parameters can be found at /oauth/authorize.

When you use hosted authentication, the user logs in using the email provider, and consents to the permissions your app requested. Instead of needing to build this flow like in Native authentication, Nylas automatically detects the provider and directs the user to the correct screen. If Nylas cannot auto-detect the user's email provider from their address, the system prompts the user with a provider selection screen.

Users see the Nylas name and logo on this page. You can upload your own icon for your user-facing Hosted Auth page from the Nylas Dashboard. Icons must be in PNG, JPG, or TIF format, and 1MB or smaller. Nylas resizes the image to 72x72 pixels, so it should be square.

Examples of provider login screens for Microsoft Exchange, IMAP, Yahoo, and Gmail.

Step 3: Get the access token

When the user signs in, the browser redirects them to the redirect_uri you specified, and Nylas stores the credentials securely.

Nylas then returns either an authorization token or code depending on the response_type value you set in Step 1. Use an access token if you are using a client-size application, or use authorization code if you are using a server-side application.

Use a client-side authorization token

When you specify a response_type of token Nylas returns an access_token as a parameter in the query string. Store the access_token in a secure place and use Javascript to remove it from the URL fragment.

That’s it! You are ready to make API requests on behalf of the user.

Use a server-side authorization code

If you set the response_type to code, Nylas returns an authorization code in the query string that you can exchange for an access_token. The authorization code is valid for 15 minutes and can be used only once.

To exchange the code for an access_token, make a POST request to /oauth/token. The required parameters are:

authorization: The Base64-encoded client secret from your Nylas application.
client_id: Your Nylas application's client ID.
client_secret: Your Nylas application's client secret.
grant_type: This is always set to authorization_code .
code: The authorization_code returned in the query string. This is the one-time use code.

You can see the full list of query parameters in the oauth/token API documentation

Example POST `/oauth/token` request

curl -X POST \
  https://api.nylas.com/oauth/token \
  -H 'Authorization: Basic ENCODED_CLIENT_SECRET' \
  -d '{
    "client_id": "<NYLAS_CLIENT_ID>",
    "client_secret": "<NYLAS_CLIENT_SECRET>",
    "grant_type": "authorization_code",
    "code": "<AUTH_EXCHANGE_CODE>"
  }'

Example POST `/oauth/token` response

{
  "access_token": "aec7cad*************",
  "account_id": "d920**********",
  "email_address": "swag@example.com",
  "provider": "eas",
  "token_type": "bearer"
}

After you exchange the authorization_code for an access_token you're ready to make API requests for your user!

Provider auto discovery

Nylas tries to identify the provider based on the information you provide. If the system can't automatically detect the provider, then it asks the user for information such as username, password, and host during the User Consent step.

Microsoft troubleshooting

Microsoft products use mobile device management (MDM) policies. This can cause a maximum of two emails in the inbox, and either can have quarantine notifications. To resolve this issue, see Checking for Quarantined EAS Devices.

More resources

Certain providers have extra requirements. Review the documentation for each.