Only show these results:
public-beta-v3

Creating Grants with OAuth and API Key

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.

Most implementations that used Nylas hosted authentication in v2.x should use the new OAuth method to get authorization from users, but then use your Nylas application's API Key to authenticate and make requests. This is the recommended auth method and easiest way to integrate with Nylas

You use the familiar hosted OAuth flow to get the user's authorization for scopes and create their grant_id, but then use an application-specific API key to access data and make other requests.

This means you only have to use the client_secret to complete the OAuth flow, but don't need it to access data, and you don't need to do any token lifecycle management with refresh keys. It also allows you to use the same request method for everything in your app, including endpoints that don't specify a Grant such as webhooks and some group calendar features.

API keys are new in Nylas v3. They are generated in the v3 Dashboard, and are specific to each Nylas application. You can set the default expiration time separately for each key, and they can be revoked from the v3 Dashboard.

Before you begin

Before you begin, make sure you set up all the required parts for your authentication system:

  1. If you haven't already, log in to the v3 Dashboard and create a new Nylas application.
    If you're using API key authentication, generate an API key in the v3 Dashboard.
  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.

Creating grants with OAuth and API Key

The rough OAuth auth process is:

  1. The end-user clicks a link or button in your app to start an OAuth request, and Nylas forwards them to the auth provider where they complete the OAuth flow, either accepting or declining the requested scopes.
  2. The auth provider directs the user back to the Nylas callback URI, and includes URL parameters that indicate success or failure, and other information.
  3. If auth was successful, Nylas creates an unverified Grant record, then forwards the user to your application's callback_uri, and includes the access code from the provider in the URL as a parameter.
  4. Your application uses the code to perform a token exchange with the provider.
  5. When the token exchange completes successfully, Nylas marks the grant record as verified and sends the grant_id to you.

At this point, instead of using doing a token exchange to get an access token for the specific user, you can use an API key you created to access the Nylas APIs. Your app can use that grant_id to specify which data to access on behalf of the user.

Start an authorization request with the provider

The first step of the auth process is to start an authorization request. Usually this is a button or link that the user clicks.

Your project redirects the end user to the auth request endpoint: GET api.us.nylas.com/v3/connect/auth, and includes their information as query parameters, as in the example below. When the user goes to this URL, Nylas starts a secure authentication session and redirects the user to the auth provider website.

/v3/connect/auth?
  client_id=<your_nylas_app_client_id>
  &redirect_uri=https://myapp.com/callback-handler // your app callback_uri
  &response_type=code
  &access_type=online 
  &provider=google //optional provider
  &state=sQ6vFQN //optional oauth context

The example also uses the access_type=online parameter to specify not to send a refresh token. This is technically optional, but we include it because we're using the API Key method, and don't want a refresh token.

There are several other optional items you can choose to pass or not:

  • provider indicates which connector your Nylas application should use. If you only have one connector you can omit this parameter. If you have more than one connector, you can either specify which one to use, or omit this and Nylas gives the user a list of connectors to choose from when they start the auth process.
  • scopes are optional if you set default scopes on the connector. Scopes set from this request override the default connector scopes.

Authorization response and grant creation

Each provider displays the consent and approval steps differently, and it's only visible to the end-user. In all cases the user authenticates, and either accepts or declines the scopes your project requested.

Next, the auth provider sends the user to the Nylas redirect_uri (https://api.us.nylas.com/connect/callback). Nylas uses the information in the response to find your Nylas application by client_id and, if the auth was successful, create an unverified Grant record for the user and record their details.

Get the user's code

Nylas then uses your Nylas application's callback_uri (for example, app.example.com/callback-handler) to forward the user back to your project. Nylas includes the code it got from the auth provider as a query parameter, as in the example below.

https://myapp.com/callback-handler?
  code=R2E_t1Mf88lipCSqrKvWZhKKzpMVXb0UOuct-U5LidwJud5vMjH1I4q...
  &state=...  //if you included a state in the initial auth request it is returned here

Token exchange and grant verified

Next you use the /v3/connect/token endpoint to exchange the code for an access token.

The auth provider responds with an access token and other information.

POST /token HTTP/1.1
Host: /v3/connect/token
Content-Type: application/json

{
  "code": "<code>",
  "client_id": "<nylas_client_id>",
  "client_secret": "<nylas_client_secret>",
  "redirect_uri": "<application_redirect_uri>", // your app callback_uri
  "grant_type": "authorization_code"
}   
{
  "access_token": "<access_token>",
  "token_type": "Bearer",
  "id_token": "<id_token>",
  "grant_id": "<grant_id>"
}

When this completes successfully, Nylas marks the user's Grant as verified and sends you the grant_id and the email address for the user.

Record the grant_id and use your API Key

As long as authentication succeeded, you can stop the OAuth process here, record the grant_id created for the user, and continue using your API key to make requests on behalf of this grant, as in the example below.

You don't need to record the user's OAuth access token, or any other OAuth information. Nylas stores what it needs in the user's Grant record.

curl --request POST \
  --url https://api.us.nylas.com/v3/grants/< the grant ID for the user>/events?calendar_id=<CALENDAR_ID> \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <your Nylas application's API key >' \
  --header 'Content-Type: application/json' \
  --data '{
  "title": "Birthday Party",
  "status": "confirmed",
  "busy": true,
  "participants": [
    {
      "name": "Aristotle",
      "email": "[email protected]",
      "status": "yes"
    }
  ],
  "description": "Come ready to skate",
  "when": 
  {
    "time": 1408875644
  },
  "location": "Roller Rink",
  "recurrence": [
    "RRULE:FREQ=WEEKLY;BYDAY=MO",
    "EXDATE:20211011T000000Z"
  ]
}