This guide goes over how to authenticate accounts using Hosted Authentication.

Nylas Hosted Auth is the quickest and easiest way to set up 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. Once your user has authenticated, the account will have an access_token to make API requests.

When to Use Hosted Authentication

• You don’t care about white-labeling your application and are okay with Nylas showing on the authentication page.
• Need to create a test application with only a few users.
  • Want to decrease development time by letting Nylas handle the authentication.

Quick Look at Hosted Authentication

There are 3 main steps to using Hosted Authentication with Nylas.

1. Redirect your user to the Nylas Hosted Auth service.
2. The user logs into their account and consents to the permissions your app requests. Nylas redirects them back to your app and provides 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.

Step 1 Redirect the User

In your application, redirect your user to the Nylas Hosted Auth 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:

• Authorization - The base64 encoded client secret from your Nylas application.
• Client ID - The client_id from your Nylas application.
• 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 2 response types;
  • Code - Set the response_type to code if you have a server-side application. Learn more about reponse_type in Step 3.
  • Token - Set the response_type to token if you have a client_side application or a mobile app. Learn more about reponse_type in Step 3.
• Scopes - Review Authentication Scopes to see available 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=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'

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

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

Step 2 User Consent

With Hosted authentication, your user will log in using the email provider and consent to the permissions your app requested. Instead of needing to build this flow like in Native authentication, Nylas will automatically detect the provider and direct the user to the correct screen.

📘

Nylas Logo

Users will see the Nylas name and logo at this stage.

📘

Auto-detect

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

Step 3 Get the Access Token

Once the user has signed in, their browser will be redirected to the redirect_uri you provided, and Nylas stores the credentials securely and then returns the response_type.

In Step 1, you provided a response_type of code or token. Depending on which you chose, determines what authorization your application receives.

Client-Side Token

Use a response_type of token if you are using a client-side application or mobile app.

A response_type of token returns an access_token as a parameter in the query string.

👍

Client-Side Token

That’s it! You are ready to make API requests on behalf of the user. We recommend storing the access_token and removing it from the URL fragment with JavaScript.

Server-Side Code

Use a response_type of code if you are using a server-side application.

A response_type of code will return a one-time use code in the query string that you can exchange for an access_token.

To exchange your code for an access_token make a POST request to /oauth/token.

The request parameters are:

• Authorization - The base64 encoded client secret from your Nylas application.
• Client ID - The client_id from your Nylas application.
• Client Secret - The client_secret from your Nylas application.
• Grant Type - This is always set to authorization_code
• Code - The authorization_code returned in the query string. This is a one-time use code.

Example /oauth/token Request

curl -X POST \
  https://api.nylas.com/oauth/token \
  -H 'Authorization: Basic ENCODED_CLIENT_SECRET' \
  -d '{
    "client_id": "CLIENT_ID",
    "client_secret": "CLIENT_SECRET",
    "grant_type": "authorization_code",
    "code": "AUTHORIZATION_CODE"
}'

Example /oauth/token Response

{
  "access_token": "aec7cad*************",
  "account_id": "d920**********",
  "email_address": "[email protected]",
  "provider": "eas",
  "token_type": "bearer"
}

👍

Server-Side Code

Now that you have exchanged your authorization_code for an access_token you are ready to make API requests on behalf of your users.

A full list of query params can be found at oauth/token.

Provider Auto Discovery

Nylas will attempt to identify the provider based on the provided information. If we are not able to, then during the User Consent step, they will be asked for information such as username, password, and host.

Keep Mind for Hosted Authentication

Now that you have learned how hosted authentication works, there are few things to think about before setting up hosted authentication.

• Decide if you want to make a server or client-side application
• Determine the scopes you need. If you need to change scopes, the user will have to reauthenticate.

Hosted Authentication Demo Apps

Take a look at our Hosted Authentication examples on GitHub.

• Ruby Hosted Authentication
• Node.js Hosted Authentication
• Python Hosted Authentication

What's Next?

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

• Google
• iCloud
• Microsoft