Only show these results:
public-beta-v3

Authentication in API v3

The Nylas API v3 is in public beta. It might contain bugs, and might change before it is generally available. See the v3 Beta documentation for more information.

This page explains the different authentication methods available in Nylas API v3, so you can choose the best one for your project. The basic steps to set up authentication are described below, but you should choose the type of authentication for your project first.

Choose an authentication method

Nylas v3 offers new, simplified, and more secure authentication methods.

  • Most Nylas applications should use the Hosted OAuth and API key method.

    This gives end-users the familiar security of OAuth, but removes the need for refresh token management after the initial token exchange. This is the recommended auth method and easiest way to integrate with Nylas.

Once you know what type of authentication you want to use, go on to the steps below.

Setting up authentication in v3

  1. If you haven't already, log in to the v3 Dashboard and create a new Nylas application.
    Get your client_id and client_secret, and if you're using API key authentication, generate an API key.
  2. Create a provider auth application in the provider's console or app.
    See the detailed instructions for Creating a v3 provider auth application in Google or Creating a v3 provider auth application in Azure.
  3. Create a connector in your Nylas application for the provider you want to authenticate with.
  4. Add your project's callback_uri-s (also called a redirect URIs) in the Nylas Dashboard.
    These are where Nylas forwards end users after an auth request.
  5. Authenticate users and create Grants.
    This process is covered in more detail in the guides for each available method.
  6. Work with user data using the grant_id.

Creating a connector

A connector stores information about external services you connect to your Nylas application, so you don't need to include them manually in all API calls. You cannot create Grants (to connect accounts) without a connector.

You only need to create a connector once per provider for each Nylas application, and you can create them either using the Dashboard v3, or using the /v3/integrations/ API endpoint.

The example below shows a POST /v3/integrations request, and the result that Nylas returns.

{
  "name": "Staging App 1",
  "provider": "microsoft",
  "settings": {
    "client_id": "abc-def",
    "client_secret": "xyz-abc-def",
    "tenant": "common"
  },
  "scope": [
    "Mail.Read",
    "User.Read",
    "offline_access"
  ]
}   
{
  "name": "Staging App 1",
  "provider": "microsoft",
  "scope": [
    "Mail.Read",
    "User.Read",
    "offline_access"
  ]
}

Creating Grants

See the instructions for each authentication method for details on creating Grants:

Bulk auth Grants and connector credentials

In v3 Nylas also supports Bulk authentication Grants (sometimes called "service accounts" or "app permissions") which you can use to do bulk re-authentication and other backend tasks.

Terms

  • Provider: The email or calendar provider that you want to connect to the Nylas platform (for example, Google or Microsoft). This can also be an IMAP provider.
  • Provider auth application: Both Microsoft and Google require that you use a verified application that runs on their platform in order to connect accounts.
  • Connector: A connector stores information in your Nylas application that allows it to connect to another service (for example, an authentication provider such as Microsoft or Google).
  • Grant: In v3, the term "grant" replaces the concept of a connected account. The Grant is a record of the user account, its provider, and the approved scopes (with other details) that Nylas was given access to when the user authenticated. For example, when you authenticate with Google, Nylas returns a Grant ID that is linked to the Google email address.
  • Scopes: Scopes define what level of access is being granted, and to what data objects on each provider. You set the scopes your project needs on your provider auth application. You can also set default scopes on each connector, and explicit scopes on each Grant.

What's next?

Now that you have created an Integration and received a Grant, you can: