Creating Grants with OAuth and API Key
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, make sure you set up all the required parts for your authentication system:
- 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.
- 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.
- Create a connector in your Nylas application for the provider you want to authenticate with.
- 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.
The rough OAuth auth process is:
- 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.
- The auth provider directs the user back to the Nylas callback URI, and includes URL parameters that indicate success or failure, and other information.
- If auth was successful, Nylas creates an unverified Grant record, then forwards the user to your application's
callback_uri, and includes the access
codefrom the provider in the URL as a parameter.
- Your application uses the
codeto perform a token exchange with the provider.
- When the token exchange completes successfully, Nylas marks the grant record as verified and sends the
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.
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.
&redirect_uri=https://myapp.com/callback-handler // your app callback_uri
&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:
providerindicates 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.
scopesare optional if you set default scopes on the connector. Scopes set from this request override the default connector scopes.
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
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.
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.
&state=... //if you included a state in the initial auth request it is returned here
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
"redirect_uri": "<application_redirect_uri>", // your app callback_uri
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.
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' \
"title": "Birthday Party",
"email": "[email protected]",
"description": "Come ready to skate",
"location": "Roller Rink",