accounts.nylas.team
Open in
urlscan Pro
2606:4700::6812:162e
Public Scan
URL:
https://accounts.nylas.team/
Submission: On November 18 via automatic, source certstream-suspicious — Scanned from DE
Submission: On November 18 via automatic, source certstream-suspicious — Scanned from DE
Form analysis 0 forms found in the DOM
Text Content
* Guides
* Getting Started
* _ Concepts
* _ Prerequisites
* _ Setting Scopes
* _ Step 1 - Create an Integration
* _ Step 2 - Creating Grants
* Authenticating
* _ Authentication OAuth 2.0
* _ Authentication OAuth 2.0 + PKCE
* _ Authentication Server-Side only
* _ Authentication Server-Side Login Screen
* _ IMAP Authentication
* _ Native Authentication
* What's Next?
* App Permissions
* About
* Microsoft App Permission via Nylas
* Google App Permission via Nylas
* Integrations
* postCreate integration
* getList integrations
* getList providers
* getAutodetect provider
* getGet integration
* patchUpdate integration
* delDelete integration
* Grants
* postNative Authentication
* getLists grants
* getGet Grant
* patchUpdate grant
* delRevoke grant
* getGet Grant from Access Token
* Authentication - OAuth 2.0 + PKCE
* getAuthorization Request
* postToken Exchange
* postRevoke
* Authentication - Server-Side only
* postHosted Auth Request
* postNative Authentication
* Credentials
* postCreate Credential
* getList Credentials
* getGet credential by ID
* patchUpdate credential by ID
* delDelete credential by ID
* Event Codes
API docs by Redocly
NYLAS AUTHENTICATION SERVICE API REFERENCE
Nylas Unified Authentication System lets you authenticate accounts against any
provider using one set of endpoints.
GUIDES
GETTING STARTED
_ CONCEPTS
* Integration - The provider you want to connect to the Nylas platform. For
example, Google and Microsoft.
* Grant - The account that was authenticated against the integration. For
example, after creating an Integration with Google, you'll then authenticate
your account with Google, and Nylas will return a Grant ID.
_ PREREQUISITES
1. Create an app in the provider's console or app. As part of your provider
settings, add the Nylas callback url
(https://{{app-name}}.us.nylas.com/connect/callback and
https://{{app-name}}-staging.us.nylas.com/connect/callback) to your
authorized or trusted redirect uris. This will give you the provider
client_id and client_secret you will use in Step 1.
2. You will need a Nylas application which will provide you with Nylas
client_id and client_secret.
3. Go to your Nylas dashboard.
4. Click App Settings.
5. Look for Developer Details. You'll use these for basic authentication
method, Authorization: Basic BASE64(CLIENT_ID:CLIENT_SECRET).
_ SETTING SCOPES
You can set scopes for the Integration and the Grant. Scopes behave differently
depending on how they are set.
_ INTEGRATION SCOPES
Scopes are optional for Integrations. If you set scopes for the Integration, any
accounts authenticated without scopes will inherit the Integration scopes.
_ GRANT SCOPES
Scopes are required for Grants. If you set the scope for a Grant, then it will
override the scopes on the Integration. You can have one Integration, and each
Grant can have its different scopes.
_ STEP 1 - CREATE AN INTEGRATION
Integrations are the provider you want to connect to the Nylas platform.
Currently, supported:
* Google
* Microsoft
You only need to create an Integration once per provider and environment. Once
you have your Integration completed, you'll only have to do steps 2-7 for each
user.
Redirect URIs
Make sure to keep note of the redirect_uris. These are used in Step 2 (hosted
only) when authenticating the user.
Example Request
POST /connect/integrations
{
"name": "Staging App 1",
"provider": "microsoft",
"settings": {
"client_id": "abc-def",
"client_secret": "xyz-abc-def",
"tenant": "common",
},
"redirect_uris": [
"http://localhost:3000",
"https://myapp.com/callback-handler"
],
"scope": [
"Mail.Read",
"User.Read",
"offline_access"
]
}
Example Response
{
"name": "Staging App 1",
"provider": "microsoft",
"redirect_uris": [
"http://localhost:3000",
"https://myapp.com/callback-handler"
],
"scope": [
"Mail.Read",
"User.Read",
"offline_access"
]
}
_ STEP 2 - CREATING GRANTS
Choose between Native and hosted Authentication to create new grants:
* Authentication OAuth 2.0
* Authentication OAuth 2.0 + PKCE
* Authentication Server-Side only
* Native Authentication
AUTHENTICATING
_ AUTHENTICATION OAUTH 2.0
STEP 1 - AUTHORIZATION REQUEST
First step of OAuth 2.0 flow is the authorization request which is redirecting
the end user to /connect/auth:
/connect/auth?
client_id=<your_nylas_app_client_id>
&redirect_uri=https://myapp.com/callback-handler
&response_type=code
&provider=google
&scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fgmail.readonly%20profile
&access_type=offline
&state=sQ6vFQN
The above example is requesting two scopes from Google (the Google Nylas
integration you have already created before this step).
STEP 2 - PROVIDER CONSENT FLOW
Immediately after getting to this page, the Nylas starts a secure authentication
session and user gets redirects to provider website. For example Google OAuth
auth url (if Google integration was selected) will be:
https://accounts.google.com/o/oauth2/auth/oauthchooseaccount?
prompt=consent&access_type=offline
&state=BA630DED06... // Stored and checked/compared internally by Nylas for security
&redirect_uri=https://accounts.nylas.com/connect/callback
&response_type=code
&client_id=<client_id> // Comes from already created integration
&scope=https://www.googleapis.com/auth/gmail.readonly%20profile
Each provider displays the consent and approval step a little differently but
eventually the user is required to accept or decline the authorization. This
flow is only visible to your application's end user in the browser.
STEP 3 - HANDLE AUTHORIZATION RESPONSE
Once the user approves/declines, Nylas redirects back to your application with
the following query params on successful authentication:
https://myapp.com/callback-handler?
state=... // Your passed state data
&code=... // Use this code value for the next step of authentication.
However, if authentication fails standard OAuth 2.0 error fields will be
returned in response (error, error_description and error_uri):
https://myapp.com/callback-handler?
state=... // Your passed state data
&error=... // Error type/constant
&error_description=... // Error description
&error_uri=... // Error or event code
STEP 4 - CODE EXCHANGE
From the previous step successful url example, code and state query params are
standard OAuth 2.0 fields. Other fields are provided by Nylas to give you more
context about the authentication and are not required by OAuth spec itself.
Next, following OAuth 2.0 flow, use the code parameter above to exchange with
tokens using /connect/token endpoint.
POST /token HTTP/1.1
Host: /connect/token
Content-Type: application/x-www-form-urlencoded
code=ljga934gkja834gasbdf93gja8934&
client_id=your_nylas_client_id&
client_secret=your_nylas_client_secret&
redirect_uri=https://myapp.com/callback-handler&
grant_type=authorization_code
In the response you will receive:
{
"access_token": "<access_token>",
"expires_in": 3600,
"refresh_token": "<refresh_token>",
"scope": "https://www.googleapis.com/auth/gmail.readonly profile",
"token_type": "Bearer",
"id_token": "<id_token>",
"grant_id": "<grant_id>"
}
Note that there is an extra optional expires_in field which allows you to
configure the expiration time of the access_token (in seconds). Best practice is
use the access token as a temporary short-lived token. The default access token
expiration is one hour. However, for client side only JavaScript applications
where you don't want to store a never expiring refresh_token in the browser, it
makes sense to increase this duration to your session duration.
STEP 5 - REFRESHING ACCESS TOKEN USING REFRESH_TOKEN (OPTIONAL)
If you asked for refresh_token by setting access_type=offline in the initial
authorization request you will receive an refresh_token in the previous step.
Per OAuth 2.0 spec, you can use this refresh_token to request a new short-lived
access token. Note that for client side only applications you should not request
offline access or need this step.
POST /token HTTP/1.1
Host: /connect/token
Content-Type: application/x-www-form-urlencoded
client_id=your_nylas_client_id&
client_secret=your_nylas_client_secret&
grant_type=refresh_token
refresh_token=<your-refresh-token>
Example response:
{
"access_token": "<access_token>",
"expires_in": 3600,
"scope": "https://www.googleapis.com/auth/gmail.readonly profile",
"token_type": "Bearer"
}
LEARN MORE
* Authorization request
* Code and token exchange
* Revoking your tokens/sessions
_ AUTHENTICATION OAUTH 2.0 + PKCE
PKCE flow is suitable for client side only applications (JavaScript and mobile
applications that do not have a backend server).
Since we should not store an application wide credential in the client side
code, the goal is to finish the code exchange flow without the use of
client_secret of your Nylas application. Note that even with applications that
have backend and can use client_secret securely it is still best practice to use
PKCE for extra security.
Same as without PKCE, first step of OAuth 2.0 flow is the authorization request
which is redirecting the end user to /connect/auth:
/connect/auth?
client_id=<your_nylas_app_client_id>
&redirect_uri=https://myapp.com/callback-handler
&response_type=code
&provider=google
&scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fgmail.readonly%20profile
&state=sQ6vFQN
&code_challenge=ZTk2YmY2Njg2YTNjMzUxMGU5ZTkyN2RiNzA2OWNiMWNiYTliOTliMDIyZjQ5NDgzYTZjZTMyNzA4MDllNjhhMg
&code_challenge_method=S256
In this example we set our code verifier string to nylas which its SHA256 hashed
equivalent is e96bf6686a3c3510e9e927db7069cb1cba9b99b022f49483a6ce3270809e68a2.
Since for extra security we chose S256 instead of plain, we provided the SHA256
version of our code verifier in the code_challenge param.
SHA256("nylas") =>
"e96bf6686a3c3510e9e927db7069cb1cba9b99b022f49483a6ce3270809e68a2"
Base64 encoded (removed padding) will be
ZTk2YmY2Njg2YTNjMzUxMGU5ZTkyN2RiNzA2OWNiMWNiYTliOTliMDIyZjQ5NDgzYTZjZTMyNzA4MDllNjhhMg
Following OAuth 2.0 flow, use the code parameter above to exchange with tokens
using /connect/token endpoint.
POST /token HTTP/1.1
Host: /connect/token
Content-Type: application/x-www-form-urlencoded
code=ljga934gkja834gasbdf93gja8934&
client_id=your_nylas_client_id&
client_secret=your_nylas_client_secret&
redirect_uri=https://myapp.com/callback-handler&
grant_type=authorization_code
code_verifier=nylas
In the above example for code_verifier we are setting the original plain text
code_verifier value.
Please note that you can not refresh your access token if client_secret is not
provided. Therefore, usually grant_type=refresh_token is not used with client
side JS/mobile applications where you don't want to store your app's
client_secret.
LEARN MORE
* Authorization request
* Code and token exchange
* Revoking your tokens/sessions
_ AUTHENTICATION SERVER-SIDE ONLY
STEP 1 - CREATE A HOSTED AUTHENTICATION REQUEST
Requires Authenticated Requests
Note that to use this approach you will need to include basic authentication in
your requests which includes your client id and secret of your Nylas
application. Therefore, this type of authentication is best suited for server
side applications.
Each user needs to be authenticated against the backend. In the request, include
one of the redirect_uris from Step 1. Otherwise, the request will fail.
As part of the response, you'll get a unique login URL. For example,
https://{{app-name}}.us.nylas.com/connect/login?id=BA630DED06.... The login URL
is only valid for a short amount of time and can only be used once.
To see the available endpoints and learn more, see Hosted Authentication.
Learn more about hosted authentication
To see the available hosted authentication endpoints see Hosted Authentication.
The steps for hosted authentication are the same in both sections.
Example Request
POST /connect/auth
{
"provider": "microsoft",
"redirect_uri": "http://localhost:3000",
"scope": [
"Mail.Read",
"User.Read",
"offline_access"
],
"state": "my-optional-state",
}
Example Response
{
"url": "https://{{app-name}}.us.nylas.com/connect/login?id=BA630DED06...",
"id": "BA630DED06...",
"expires_at": <epoch>,
"request": {
"redirect_uri": "https://myapp.com/callback-handler",
"provider": "microsoft",
"scope": [
"Mail.Read",
"User.Read",
"offline_access"
],
"state": "my-optional-state",
}
}
STEP 2 - REDIRECT TO NYLAS LOGIN REDIRECT
Direct the user to the unique url ID returned when you created the Hosted Auth
request in Step 2. Then Nylas will redirect them to the provider.
Example Request
GET https://{{app-name}}.us.nylas.com/connect/login?id=USER-LOGIN-ID
Example Response
HTTP 302 Redirect to:
https://accounts.google.com/o/oauth2/auth/oauthchooseaccount?
prompt=consent&login_hint=email@google.com&access_type=offline
&state=BA630DED06... // Stored and checked/compared internally by Nylas for security
&redirect_uri=https://{{app-name}}.us.nylas.com/connect/callback
&response_type=code
&client_id=<client_id> // Comes from already created integration
&scope=https://www.googleapis.com/auth/gmail.readonly
STEP 3 - USER IS REDIRECTED BACK TO NYLAS
After the user has approved the permissions and is redirected back to the Nylas
callback url which is in https://{{app-name}}.us.nylas.com/connect/callback,
Nylas will:
* Store the user’s email address
* Get a refresh token
* Validate the refresh token
If the provider is of type email (eg: gmail) that is syncable, Nylas will start
syncing the grant messages immediately at this step.
STEP 4 - NYLAS REDIRECTS THE USER BACK TO YOUR APP
Nylas will send the user back to the redirect_uri specified in the original
Hosted Auth request in Step 2.
HTTP 302 Redirect to:
https://myapp.com/callback-handler?success=true&grant_id=e19f8e1a-eb1c-41c0-b6a6-d2e59daf7f47...&state=my-data&provider=google&email=...
_ AUTHENTICATION SERVER-SIDE LOGIN SCREEN
STEP 1 - CREATE A HOSTED AUTHENTICATION REQUEST
Requires Authenticated Requests
Note that to use this approach you will need to include basic authentication in
your requests which includes your client id and secret of your Nylas
application. Therefore, this type of authentication is best suited for server
side applications.
Requires At Least Two OAuth providers
Note that to access the login screen inside your application you will need at
least two OAuth integraions. If only one integraion exists the user will
automaticly be redirected to that provider OAuth concent screen.
Each user needs to be authenticated against the backend. In the request, include
one of the redirect_uris from Step 1. Otherwise, the request will fail.
As part of the response, you'll get a unique auth URL. For example,
https://{{app-name}}.us.nylas.com/connect/auth?prompt=detect,select_provider....
The auth URL is used to get the user to the provider select or detect screen
depending on the configuration provided
To see the available endpoints and learn more, see Hosted Authentication.
Learn more about hosted authentication
To see the available hosted authentication endpoints see Hosted Authentication.
The steps for hosted authentication are the same in both sections.
Example Request
POST /connect/auth
{
"redirect_uri": "http://localhost:3000",
"prompt":"select_provider,detect",
"state": "my-optional-state",
}
Example Response
{
"url": "https://{{app-name}}.us.nylas.com/connect/auth?prompt=select_provider,detect...",
"id": "BA630DED06...",
"request": {
"redirect_uri": "https://myapp.com/callback-handler",
"prompt":"select_provider,detect",
"state": "my-optional-state",
}
}
STEP 2 - REDIRECT TO NYLAS LOGIN PAGE & CHOOSES A PROVIDER
Direct the user to the Nylas Login Page where he can choose between OAuth
providers that he wants to authenticate with
Example Request
GET
https://{{app-name}}.us.nylas.com/connect/auth?redirect_uri=https://myapp.com/callback-handler&state=my-optional-state&prompt=select_provider,detect&client_id=<NYLAS_CLIENT_ID>
Example Page
In this example user has created two OAuth integrations so he sees two providers
and also has the detect prompt enabled. The Login Page also takes in account the
Hosted settings you provide to your Application and changes the UI according to
your configuration. Note that the order of prompts and providers metter inside
the initial request.
STEP 3 - USER IS REDIRECTED BACK TO NYLAS
After the user has approved the permissions and is redirected back to the Nylas
callback url which is in https://{{app-name}}.us.nylas.com/connect/callback,
Nylas will:
* Store the user’s email address
* Get a refresh token
* Validate the refresh token
If the provider is of type email (eg: gmail) that is syncable, Nylas will start
syncing the grant messages immediately at this step.
STEP 4 - NYLAS REDIRECTS THE USER BACK TO YOUR APP
Nylas will send the user back to the redirect_uri specified in the original
Hosted Auth request in Step 2.
HTTP 302 Redirect to:
https://myapp.com/callback-handler?success=true&grant_id=e19f8e1a-eb1c-41c0-b6a6-d2e59daf7f47...&state=my-data&provider=google&email=...
_ IMAP AUTHENTICATION
STEP 1 - CREATE THE INTEGRATION
IMAP does not support the concept of scopes - so you do not need to provide it
during the authentication process.
POST /connect/integrations
{
"name": "Staging App 1",
"provider": "imap",
"redirect_uris": [
"http://localhost:3000",
"https://myapp.com/callback-handler"
]
}
STEP 2A - NATIVE AUTH FOR YAHOO
Yahoo does not support OAuth, so instead of providing a refresh token, you need
to provide a username, password, host, port, and type during the Native Auth
process.
POST /connect/grants
{
"provider": "imap",
"settings": {
"imap_username": "john.doe@yahoo.com",
"imap_password": "super-secret-app-password",
"imap_host": "imap.mail.yahoo.com",
"imap_port": 993,
"type": "yahoo"
}
}
STEP 2B - HOSTED AUTH FOR YAHOO
Nylas Support Hosted Authentication for Yahoo. In order to redirect to the UI
for end users to login in using their Yahoo accounts, settings.type must be set
to yahoo during the API request
POST /connect/auth
{
"provider": "imap",
"redirect_uri": "http://localhost:3000",
"settings": {
"type": "yahoo"
}
}
Once this setup is complete, please proceed with the exact same steps as
specified in the Hosted Authentication documentation
Regarding error handling:
* An IMAP hosted authentication has very specific events including
invalid_authentication, provider_not_responding and auth_limit_reached.
* If the IMAP provider (eg: Yahoo IMAP server) did not respond to the login
request from Nylas, the login asynchronous validation shows the proper error
message for provider_not_responding event.
* If the Provider responded with incorrect credential error, user is prompted
with an error message. For Yahoo we will hint the user and link them to Yahoo
guide for creating an application password.
* If user entered the wrong password 3 times incorrectly instead of an error
message, Nylas hosted authentication redirects back to your application
redirect_uri with the error code for auth_limit_reached.
* A grant is only created for IMAP if all the validations have passed
successfully for the IMAP settings and credentials.
_ NATIVE AUTHENTICATION
If you are handling the OAuth flow in your own application or want to migrate
existing users, Native Authentication allows you to simply provide the user
refresh_token in order to create a grant.
Example Request
POST /connect/grants
{
"provider": "microsoft",
"settings": {
"refresh_token": "1//06lIzwlbg4SgLCgY..."
}
}
Example Response
{
"success": true,
"data": {
"id": "e19f8e1a-eb1c-41c0-b6a6-d2e59daf7f47",
"provider": "microsoft",
"grant_status": "valid",
"email": "email@hotmail.com",
"scope": [
"Mail.Read",
"User.Read",
"offline_access"
],
"user_agent": "string",
"ip": "string",
"state": "my-state",
"created_at": 1617817109,
"updated_at": 1617817109
}
}
WHAT'S NEXT?
Now that you have created an Integration and received a Grant, you can:
* Manage your Integrations
* Manage your Grants
* Review the Event codes
APP PERMISSIONS
ABOUT
An app permission account is a special kind of account used by an application or
compute workload rather than a person. Applications can use app permission
accounts to make authorize API calls instead of users. App permission is
colloquially known as Service Accounts.
More info about Google's Service Accounts can be found in official Google or
Microsoft documentation.
MICROSOFT APP PERMISSION VIA NYLAS
PRE-REQUIRED ACTIONS
In Microsoft Azure it is necessary to create new application.
After the application has been created, open the application iz Microsoft
Azure's dashboard to get ready for application setup.
Application setup:
1. in Authentication tab add a new platform and set its redirect URI. For
example, select web platform and add redirect uri for Nylas callback API
call. It is really important to add Nylas' callback API as redirect URI (for
example: https://xyz.us.nylas.com/connect/callback)
2. in Certificates & secrets tab add new client secret. Save given value of
secret somewhere, since only once this is visible, right after creation!
3. in API permissions it is necessary to add all the scopes of Microsoft Graph
that this application (and App Permission) can have access to. It is not
necessary to "Grant admin consent", since that will be done later via Nylas
special authorization API call
4. in Owners tab add the admin user which will grant consent when the time
comes, after Nylas special authorization API call
5. in Manifest tab be sure the following two values are set:
"accessTokenAcceptedVersion": 2 and "signInAudience":
"AzureADandPersonalMicrosoftAccount"
NYLAS APIS
Nylas APIs will do all the hard work for you :)
1. for your Nylas application, make sure you have a Microsoft integration
(hint: use GET /connect/integrations to check).
2. create your unique Nylas credential for Microsoft account (how to create
Nylas credential)
In body for credential creation include original provider's client id and
client secret, and then this client id and client secret will be used when
creating Nylas MicrosoftApp Permisson with this credential.
Body for credential can contain only two basic information for Microsoft
credential:
{
"name": "test credential Microsoft", #REQUIRED
"credential_type": "adminconsent" #REQUIRED
"credential_data": {
"client_id": "abcd1234-abcd-1234-b558-abcd1234", #REQUIRED, PROVIDER ORIGINAL
"client_secret": "lsu2Ek~R2swQDSe_Cx3NuLrI7wBXxZn~hyt6MLLO" #REQUIRED, PROVIDER ORIGINAL
}
}
3. in response of this Nylas credential creation API call response body is
going to look something like following
{
"success": true,
"data": {
"id": "e19f8e1a-eb1c-41c0-b6a6-d2e59daf7f47",
"integration_id": "d1n4M0ZG-ac12-13ab-98ed-1fe33cbd43a1",
"name": "test credential Microsoft",
"created_at": 1656082371,
"updated_at": 1656082371
}
}
It is important to save id, which represents the ID of newly created Nylas
credential record, since that will be used in the future.
4. call Nylas authorization API, GET /connect/auth, which will do work in
background and at one point request admin's action to approve (or decline)
the requested scope access. The scopes that the access is requested for are
the same scopes previously defined in Microsoft Azure application.
API call can look something like following
https://xyz.us.nylas.com/connect/auth?
provider=microsoft&
redirect_uri=localhost:5000/callback&
response_type=adminconsent&
state=state1234&
credential_id=e19f8e1a-eb1c-41c0-b6a6-d2e59daf7f47&
client_id=71dd22z6os123fgev42xnxbq
where the following query params are:
1. provider : provider name (for this example always microsoft)
2. redirect_uri : redirect uri where user wants the Nylas callback to
redirect to
3. response_type: for this example always adminconsent
4. state: optional, will be returned to URL response as a security check
feature
5. credential_id: id of Nylas credential record previously created
6. client_id: id of Nylas application this whole process is used for
If Microsoft's Admin Consent flow was successful, a response will be an
automated redirect to redirect_uri, and in response URL flags
"admin_consent:true" and response of a previously given "state" param.
5. after this call we can create an app permission grant, which actually is a
Microsoft App Permission account in Nylas ecosystem An example of this call
is as follows: POST https://xyz.us.nylas.com/connect/grants with body
{
"provider": "microsoft", #REQUIRED
"settings": {
"credential_id": "e19f8e1a-eb1c-41c0-b6a6-d2e59daf7f47", #REQUIRED
"email_address": "user@office365.com" #REQUIRED
}
}
where the params are as follows:
1. provider: name of provider (for this example always microsoft)
2. settings: settings of this grant
1. credential_id: id of Nylas credential record previously created
2. email_address: email of Microsoft account we wish to create grant for,
and for this account we can make App Permission calls (if a Grant for
the provided email already exists, a Grant's re-auth will
automatically be initiated)
6. response of this special grant App Permission creation will be the same as
for normal grant, but with one added information: provider_user_id!
This provider_user_id is actually a UUID that provider uses for given email
address and can be used, with provider access token encoded and secretly and
securely stored in Nylas database, to call Microsoft Graph APIs in that
users' email address name (as App Permission).
GOOGLE APP PERMISSION VIA NYLAS
PRE-REQUIRED ACTIONS
In Google Cloud Platform it is necessary to create new application.
After the application has been created, open the application iz Microsoft
Azure's dashboard to get ready for application setup.
Application setup: TODO @JonnyH: write more details here!
NYLAS APIS
Nylas APIs will do all the hard work for you :)
1. for your Nylas application, make sure you have a Google integration (hint:
use GET /connect/integrations to check).
2. create your unique Nylas credential for Google account (how to create Nylas
credential)
Body for credential must contain more details for Google credential, since
Google doesn't require admin consent for scopes (as Microsoft does), but the
scopes are defined for each grant individually:
{
"name": "credential Google", #REQUIRED
"credential_type": "serviceaccount", #REQUIRED
"credential_data": {
"type": "service_account",
"project_id": "marketplace-sa-test",
"private_key_id": "private123456key", #REQUIRED
"private_key": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n", #REQUIRED
"client_email": "name@marketplace-sa-test.iam.gserviceaccount.com", #REQUIRED
"client_id": "123456789123456789123",
"auth_uri": "https://accounts.google.com/o/oauth2/auth",
"token_uri": "https://oauth2.googleapis.com/token",
"auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
"client_x509_cert_url": "https://www.googleapis.com/robot/v1/metadata/x509/name%40marketplace-sa-test.iam.gserviceaccount.com"
}
}
3. in response of this Nylas credential creation API call response body is
going to look something like following
{
"success": true,
"data": {
"id": "e19f8e1a-eb1c-41c0-b6a6-d2e59daf7f47",
"integration_id": "d1n4M0ZG-ac12-13ab-98ed-1fe33cbd43a1",
"name": "credential Google",
"created_at": 1656082371,
"updated_at": 1656082371
}
}
It is important to save id, which represents the ID of newly created Nylas
credential record, since that will be used in the future.
4. after this call we can create an App Permission grant, which actually is
Google App Permission (Google calls it Service Account) in Nylas ecosystem.
An example of this call is as follows: POST
https://xyz.us.nylas.com/connect/grants with body
{
"provider": "google", #REQUIRED
"settings": {
"credential_id": "e19f8e1a-eb1c-41c0-b6a6-d2e59daf7f47", #REQUIRED
"email_address": "user@google.com", #REQUIRED
"scopes" : ["https://www.googleapis.com/auth/gmail.readonly"] #REQUIRED
}
}
where the params are as follows:
1. provider: name of provider (for this example always google)
2. settings: settings of this grant
1. credential_id: id of Nylas credential record previously created
2. email_address: email of Google account we wish to create grant for,
and for this account we can make App Permission calls (if a Grant for
the provided email already exists, a Grant's re-auth will
automatically be initiated)
3. scopes: space delimited list of scopes we wish to gain access to via
this App Permission, but only for given email address' account
5. response of this special grant App Permission creation will be the same as
for normal grant, but with one added information: provider_user_id!
This provider_user_id is actually an email that provider uses for given user
and can be used, with provider access token encoded and secretly and
securely stored in Nylas database, to call Google Gmail APIs in that users'
email address name (as Google's Service Account does).
INTEGRATIONS
CRUD operations for management of integrations.
CREATE INTEGRATION
Customer Developer onboarding setup up OAuth strategy with ClientID/Secrets.
AUTHORIZATIONS:
BasicAuth
REQUEST BODY SCHEMA: APPLICATION/JSON
name
required
string
Name of the integation (for your reference)
provider
required
string
Enum: "google" "microsoft" "imap"
Oauth provider
settings
object
Oauth provider credentials and settings
redirect_uris
Array of strings <url>
Allowed redirect URIs (for hosted authentication)
expires_in
integer <int32> >= 60
Default: 43200
How long login urls/sessions for server side hosted authentications will remain
valid before the link expires. Defaults to 12 hours (43,200 seconds)
scope
Array of strings
Set the scopes for each integration. These scopes will be the default for your
application. See Setting Scopes for more.
RESPONSES
201
Integration Created
400
Bad Request
401
Not Authenticated
post/connect/integrations
Application
https://{{app-name}}.us.nylas.com/connect/integrations
REQUEST SAMPLES
* Payload
Content type
application/json
Copy
Expand all Collapse all
{
* "name": "Sample Zoom integration",
* "provider": "google",
* "settings": {
* "client_id": "abc-def",
* "client_secret": "xyz-abc-def"
},
* "redirect_uris": [
* "http://localhost:3000",
* "https://myapp.com/callback-handler"
],
* "expires_in": 43200,
* "scope": [
* "user:read",
* "user:write"
]
}
RESPONSE SAMPLES
* 201
* 400
* 401
Content type
application/json
Copy
Expand all Collapse all
{
* "success": true,
* "data": {
* "name": "My first integration",
* "provider": "google",
* "settings": {
* "tenant": "common"
},
* "redirect_uris": [
* "http://localhost:3000",
* "https://myapp.com/callback-handler"
],
* "scope": [
* "user:read",
* "user:write"
]
}
}
LIST INTEGRATIONS
Lists your integrations
AUTHORIZATIONS:
BasicAuth
QUERY PARAMETERS
limit
any
Limit the number of integration results
offset
any
Offset integration results
RESPONSES
200
Returns array of Integration objects
401
Not Authenticated
404
Not Found
get/connect/integrations
Application
https://{{app-name}}.us.nylas.com/connect/integrations
RESPONSE SAMPLES
* 200
* 401
* 404
Content type
application/json
Copy
Expand all Collapse all
{
* "data": [
* {
* "name": "My first integration",
* "provider": "google",
* "settings": {
* "tenant": "common"
},
* "redirect_uris": [
* "http://localhost:3000",
* "https://myapp.com/callback-handler"
],
* "scope": [
* "user:read",
* "user:write"
]
}
],
* "limit": 10,
* "offset": 0
}
LIST PROVIDERS
Lists your available Oauth providers
QUERY PARAMETERS
client_id
required
string
ID of client/application that you want to see the provider list for
RESPONSES
200
Returns array of Provider objects
404
Not Found
get/connect/providers/find
Application
https://{{app-name}}.us.nylas.com/connect/providers/find
RESPONSE SAMPLES
* 200
* 404
Content type
application/json
Copy
Expand all Collapse all
{
* "data": [
* {
* "provider": "google"
}
]
}
AUTODETECT PROVIDER
Returns detected provider if it is found
AUTHORIZATIONS:
BasicAuth
QUERY PARAMETERS
email
required
string
Email for detection
all_provider_types
boolean
Default: false
Search by all providers regardless of created integrations
client_id
string
If present no need to use Basic auth
RESPONSES
200
Returns the autodetected provider
401
Not Authenticated
get/connect/providers/detect
Application
https://{{app-name}}.us.nylas.com/connect/providers/detect
RESPONSE SAMPLES
* 200
* 401
Content type
application/json
Copy
Expand all Collapse all
{
* "data": {
* "provider": "google",
* "type": "google",
* "email": "test@gmail.com",
* "detected": true
}
}
GET INTEGRATION
Gets an integration based on provided ID
AUTHORIZATIONS:
BasicAuth
PATH PARAMETERS
provider
required
any
Example: google
RESPONSES
200
Returns Integration object
401
Not Authenticated
404
Not Found
get/connect/integrations/:provider
Application
https://{{app-name}}.us.nylas.com/connect/integrations/:provider
RESPONSE SAMPLES
* 200
* 401
* 404
Content type
application/json
Copy
Expand all Collapse all
{
* "data": {
* "name": "My first integration",
* "provider": "google",
* "settings": {
* "tenant": "common"
},
* "redirect_uris": [
* "http://localhost:3000",
* "https://myapp.com/callback-handler"
],
* "scope": [
* "user:read",
* "user:write"
]
}
}
UPDATE INTEGRATION
Updates an integration based on provided ID
AUTHORIZATIONS:
BasicAuth
PATH PARAMETERS
provider
required
any
Example: google
REQUEST BODY SCHEMA: APPLICATION/JSON
name
string
Name of the integation (for your reference)
redirect_uris
Array of strings <url>
Allowed redirect URIs (for hosted authentication)
expires_in
integer <int32> >= 60
Default: 1209600
Issue the JWT token with the specified expiration date. Defaults to 14 days
(1,209,600 seconds)
settings
object
Oauth provider credentials and settings
scope
Array of strings
Oauth "scope" parameter
RESPONSES
200
Returns integration object
400
Bad Request
401
Not Authenticated
404
Not Found
patch/connect/integrations/:provider
Application
https://{{app-name}}.us.nylas.com/connect/integrations/:provider
REQUEST SAMPLES
* Payload
Content type
application/json
Copy
Expand all Collapse all
{
* "name": "Sample Zoom integration",
* "redirect_uris": [
* "http://localhost:3000",
* "https://myapp.com/callback-handler"
],
* "expires_in": 1209600,
* "settings": {
* "tenant": "common"
},
* "scope": [
* "Mail.Read",
* "User.Read",
* "offline_access"
]
}
RESPONSE SAMPLES
* 200
* 400
* 401
* 404
Content type
application/json
Copy
Expand all Collapse all
{
* "success": true,
* "data": {
* "name": "My first integration",
* "provider": "google",
* "settings": {
* "tenant": "common"
},
* "redirect_uris": [
* "http://localhost:3000",
* "https://myapp.com/callback-handler"
],
* "scope": [
* "user:read",
* "user:write"
]
}
}
DELETE INTEGRATION
Delete existing integration based on provided ID
AUTHORIZATIONS:
BasicAuth
PATH PARAMETERS
provider
required
any
Example: google
RESPONSES
200
Delete Succeed
401
Not Authenticated
404
Not Found
delete/connect/integrations/:provider
Application
https://{{app-name}}.us.nylas.com/connect/integrations/:provider
RESPONSE SAMPLES
* 200
* 401
* 404
Content type
application/json
Copy
Expand all Collapse all
{
* "success": true,
* "data": {
* "message": "Resource successfully removed"
}
}
GRANTS
CRUD operations for management of grants. This includes getting, finding,
revoking and re-authenticating existing grants, or creating a new grant via
Native Auth
NATIVE AUTHENTICATION
Manually create grant for a native authentication. If you are handling the OAuth
flow in your own application or want to migrate existing users, Native
Authentication allows you to simply provide the user refresh_token in order to
create a grant.
AUTHORIZATIONS:
BasicAuth
REQUEST BODY SCHEMA: APPLICATION/JSON
One of
Refresh TokenCredential OverrideApp Permission MicrosoftApp Permission
GoogleIMAP
provider
required
string
Enum: "google" "microsoft"
Oauth provider
settings
required
object
Settings required by provider. Here is added "refresh_token" attribute with its
value.
scope
Array of strings
If not specified it will use the integration default scopes. See Setting Scopes
for more.
state
string
Optional state value to return to developer's website after authentication flow
is completed
RESPONSES
201
Grant Created
400
Bad Request
401
Not Authenticated
post/connect/grants
Application
https://{{app-name}}.us.nylas.com/connect/grants
REQUEST SAMPLES
* Payload
Content type
application/json
Example
Refresh TokenCredential OverrideApp Permission MicrosoftApp Permission
GoogleIMAPRefresh Token
Copy
Expand all Collapse all
{
* "provider": "google",
* "settings": {
* "refresh_token": "1//09XpDHQ6hq6PrCgYIARAAGAkSNwF..."
},
* "scope": [
* "Mail.Read",
* "User.Read",
* "offline_access"
],
* "state": "my-state"
}
RESPONSE SAMPLES
* 201
* 400
* 401
Content type
application/json
Copy
Expand all Collapse all
{
* "success": true,
* "data": {
* "id": "e19f8e1a-eb1c-41c0-b6a6-d2e59daf7f47",
* "provider": "google",
* "grant_status": "valid",
* "email": "email@hotmail.com",
* "scope": [
* "Mail.Read",
* "User.Read",
* "offline_access"
],
* "user_agent": "string",
* "ip": "string",
* "state": "my-state",
* "created_at": 1617817109,
* "updated_at": 1617817109,
* "provider_user_id": "b16f171c-6640-4edd-a598-e507b546d841"
}
}
LISTS GRANTS
Lists grants for integration
AUTHORIZATIONS:
BasicAuth
QUERY PARAMETERS
limit
integer
Default: 10
Limit the number of grant results
offset
integer
Default: 0
Offset grant results
sort_by
string
Default: "created_at"
Enum: "created_at" "updated_at"
Sort entries by field name
order_by
string
Default: "desc"
Enum: "desc" "asc"
Specify ascending or descending order
since
int
Scope grants from a specific point in time by created_at
before
int
Scope grants to a specific point in time by created_at
email
string
Filtering your query based on grant email address (if applicable)
grant_status
string
Filtering your query based on grant email status (if applicable)
ip
string
Filtering your query based on grant IP address
provider
string
Oauth provider
RESPONSES
200
Returns array of Grant objects
401
Not Authenticated
404
Not Found
get/connect/grants
Application
https://{{app-name}}.us.nylas.com/connect/grants
RESPONSE SAMPLES
* 200
* 401
* 404
Content type
application/json
Copy
Expand all Collapse all
{
* "data": [
* {
* "id": "e19f8e1a-eb1c-41c0-b6a6-d2e59daf7f47",
* "provider": "google",
* "grant_status": "valid",
* "email": "email@hotmail.com",
* "scope": [
* "Mail.Read",
* "User.Read",
* "offline_access"
],
* "user_agent": "string",
* "ip": "string",
* "state": "my-state",
* "created_at": 1617817109,
* "updated_at": 1617817109,
* "provider_user_id": "b16f171c-6640-4edd-a598-e507b546d841"
}
],
* "limit": 10,
* "offset": 0
}
GET GRANT
Gets an integration based on provided ID
AUTHORIZATIONS:
BasicAuth
PATH PARAMETERS
grantId
required
any
Example: 5967ca40-a2d8-4ee0-a0e0-6f18ace39a90
RESPONSES
200
Returns Grant object
401
Not Authenticated
404
Not Found
get/connect/grants/:grantId
Application
https://{{app-name}}.us.nylas.com/connect/grants/:grantId
RESPONSE SAMPLES
* 200
* 401
* 404
Content type
application/json
Copy
Expand all Collapse all
{
* "data": {
* "id": "e19f8e1a-eb1c-41c0-b6a6-d2e59daf7f47",
* "provider": "google",
* "grant_status": "valid",
* "email": "email@hotmail.com",
* "scope": [
* "Mail.Read",
* "User.Read",
* "offline_access"
],
* "user_agent": "string",
* "ip": "string",
* "state": "my-state",
* "created_at": 1617817109,
* "updated_at": 1617817109,
* "provider_user_id": "b16f171c-6640-4edd-a598-e507b546d841"
}
}
UPDATE GRANT
Modify existing grant with partial update. Only fields that are included in the
payload will be updated.
AUTHORIZATIONS:
BasicAuth
PATH PARAMETERS
grantId
required
any
Example: 5967ca40-a2d8-4ee0-a0e0-6f18ace39a90
REQUEST BODY SCHEMA: APPLICATION/JSON
settings
object
Settings required by provider
scope
Array of strings
Oauth "scope" parameter
RESPONSES
200
Returns Grant object
400
Bad Request
401
Not Authenticated
404
Not Found
patch/connect/grants/:grantId
Application
https://{{app-name}}.us.nylas.com/connect/grants/:grantId
REQUEST SAMPLES
* Payload
Content type
application/json
Copy
Expand all Collapse all
{
* "settings": {
* "refresh_token": "adadada..."
},
* "scope": [
* "Mail.Read",
* "User.Read",
* "offline_access"
]
}
RESPONSE SAMPLES
* 200
* 400
* 401
* 404
Content type
application/json
Copy
Expand all Collapse all
{
* "success": true,
* "data": {
* "id": "e19f8e1a-eb1c-41c0-b6a6-d2e59daf7f47",
* "provider": "google",
* "grant_status": "valid",
* "email": "email@hotmail.com",
* "scope": [
* "Mail.Read",
* "User.Read",
* "offline_access"
],
* "user_agent": "string",
* "ip": "string",
* "state": "my-state",
* "created_at": 1617817109,
* "updated_at": 1617817109,
* "provider_user_id": "b16f171c-6640-4edd-a598-e507b546d841"
}
}
REVOKE GRANT
Delete existing grant based on provided ID
AUTHORIZATIONS:
BasicAuth
PATH PARAMETERS
grantId
required
any
Example: 5967ca40-a2d8-4ee0-a0e0-6f18ace39a90
RESPONSES
200
Delete Succeed
401
Not Authenticated
404
Not Found
delete/connect/grants/:grantId
Application
https://{{app-name}}.us.nylas.com/connect/grants/:grantId
RESPONSE SAMPLES
* 200
* 401
* 404
Content type
application/json
Copy
Expand all Collapse all
{
* "success": true,
* "data": {
* "message": "Resource successfully removed"
}
}
GET GRANT FROM ACCESS TOKEN
Gets a grant based on UAS issued access token (Hosted OAuth) provided inside
Bearer Auth
AUTHORIZATIONS:
BearerAuth
RESPONSES
200
Returns Grant object
401
Not Authenticated
404
Not Found
get/connect/grants/me
Application
https://{{app-name}}.us.nylas.com/connect/grants/me
RESPONSE SAMPLES
* 200
* 401
* 404
Content type
application/json
Copy
Expand all Collapse all
{
* "data": {
* "id": "e19f8e1a-eb1c-41c0-b6a6-d2e59daf7f47",
* "provider": "google",
* "grant_status": "valid",
* "email": "email@hotmail.com",
* "scope": [
* "Mail.Read",
* "User.Read",
* "offline_access"
],
* "user_agent": "string",
* "ip": "string",
* "state": "my-state",
* "created_at": 1617817109,
* "updated_at": 1617817109,
* "provider_user_id": "b16f171c-6640-4edd-a598-e507b546d841"
}
}
AUTHENTICATION - OAUTH 2.0 + PKCE
AUTHORIZATION REQUEST
The initial OAuth 2.0 authorization request which supports the authorization
code flow in addition to optional PKCE for client side only applications. Learn
more:
* Authentication OAuth 2.0
* Authentication OAuth 2.0 + PKCE
QUERY PARAMETERS
client_id
required
string
Nylas application client_id (or application id)
provider
required
string
Enum: "google" "microsoft"
The integration provider type that you have already setup with Nylas for this
application
redirect_uri
required
string
Redirect URI of the integration
response_type
required
string
Enum: "code" "adminconsent"
Should be set to code for Nylas OAuth2.0 flow, and set to 'adminconsent' for
Microsoft admin consent service account flow.
scope
string
A space-delimited list of scopes that identify the resources that your
application could access on the user's behalf. If no scope is given, all of the
default integration's scopes are used.
state
string
Optional state to be returned after authentication
login_hint
string
Prefill the login name (usually email) during authorization flow. If a Grant for
the provided email already exists, a Grant's re-auth will automatically be
initiated.
access_type
string
Enum: "offline" "online"
If the exchange token should return refresh_token too. Not suitable for client
side or JavaScript apps.
code_challenge
string
Example:
code_challenge=e96bf6686a3c3510e9e927db7069cb1cba9b99b022f49483a6ce3270809e68a2
Specifies an encoded code_verifier that will be used as a server-side challenge
during authorization code exchange.
code_challenge_method
string
Default: "plain"
Enum: "plain" "S256"
Example: code_challenge_method=S256
Specifies what method was used to encode a code_verifier that will be used
during authorization code exchange.
credential_id
string
Example: credential_id=e19f8e1a-eb1c-41c0-b6a6-d2e59daf7f47
ID of previously created Nylas credential record. This is only set for Microsoft
admin consent service account flow!
RESPONSES
302
Redirects to the selected providers authorization page
get/connect/auth
Application
https://{{app-name}}.us.nylas.com/connect/auth
RESPONSE SAMPLES
* 302
Content type
schema
Copy
https://accounts.google.com/o/oauth2/auth/oauthchooseaccount?prompt=consent&login_hint=email@google.com&access_type=offline&state=<BA630DED06...> &redirect_uri=https://accounts.nylas.com/connect/callback&response_type=code&client_id=<client_id>
TOKEN EXCHANGE
OAuth 2.0 standard token endpoint provided for use case:
* authorization_code: Exchange code returned from OAuth 2.0 authorization with
tokens (access_token & refresh_token).
* refresh_token: Issue a new access_token using refresh_token
Learn More:
* Authentication OAuth 2.0
* Authentication OAuth 2.0 + PKCE
REQUEST BODY SCHEMA: APPLICATION/JSON
One of
Exchange CodeRefresh access token
client_id
required
string
Nylas application client_id (or application id)
client_secret
required
string
Nylas application client_secret
grant_type
required
string
Value: "authorization_code"
Supports exchanging the code for tokens, or refreshing an access token using
refresh_token.
code
required
string
OAuth 2.0 code fetched from the previous step.
redirect_uri
required
string <url>
Should match the same redirect_uri that was used for getting the code during the
initial authorization request.
code_verifier
string
The original plain text code verifier created in authorization step.
RESPONSES
200
400
post/connect/token
Application
https://{{app-name}}.us.nylas.com/connect/token
REQUEST SAMPLES
* Payload
Content type
application/json
Example
Exchange CodeRefresh access tokenExchange Code
Copy
{
* "client_id": "nylas_app_client_id",
* "client_secret": "nylas_app_client_secret",
* "grant_type": "authorization_code",
* "code": "string",
* "redirect_uri": "https://myapp.com/callback-handler",
* "code_verifier": "nylas"
}
RESPONSE SAMPLES
* 200
* 400
Content type
application/json
Copy
{
* "access_token": "<access_token>",
* "expires_in": 3600,
* "id_token": "<jwt_id_token>",
* "refresh_token": "<refresh_token>",
* "scope": "https://www.googleapis.com/auth/gmail.readonly profile",
* "token_type": "Bearer",
* "grant_id": "<grant_id>"
}
REVOKE
Revoke a token an the the grant attached to that token. Note that revoking an
using your access token will also revoke all the sibling tokens and the parent
refresh_token attached to your token.
Furthermore Nylas tries its best to also programmatically revoke all the
providers tokens/sessions in the underlying linked grants.
QUERY PARAMETERS
token
required
any
The token to revoke
RESPONSES
200
400
post/connect/revoke
Application
https://{{app-name}}.us.nylas.com/connect/revoke
RESPONSE SAMPLES
* 200
* 400
Content type
application/json
Copy
{ }
AUTHENTICATION - SERVER-SIDE ONLY
HOSTED AUTH REQUEST
Create a new authorization request and get a new unique login url. Used only for
hosted authentication. This is the initial step requested from the server side
to issue a new login url. The response gives you a url that you can redirect
your end user to. The generated url expires in a short duration and can only be
used once and for one attempt. The login url keeps the state and other claims
private to Nylas while it internally manages its own hashed state for security.
{
"success": true,
"data": {
"url": "/connect/login?id=BA630DED06...",
"id": "BA630DED06...",
"expires_at": 0,
"request": {
"redirect_uri": "https://myapp.com/callback-handler",
"provider": "google",
"scope": [
"https://www.googleapis.com/auth/gmail.readonly"
],
"login_hint": "email@gmail.com",
"state": "my-state"
}
}
}
Note: If a Grant for the provided email already exists, a Grant's re-auth will
automatically be initiated.
In the above example response data.url is where the end user of your app gets
redirected to.
/connect/login?id=...
Immediately after getting to this page, the OAuth flow secure session starts and
user redirects to provider website. For example Google OAuth auth url will be:
https://accounts.google.com/o/oauth2/auth/oauthchooseaccount?
prompt=consent&login_hint=email@google.com&access_type=offline
&state=BA630DED06... // Stored and checked/compared internally by Nylas for security
&redirect_uri=https://accounts.nylas.com/connect/callback
&response_type=code
&client_id=<client_id> // Comes from already created integration
&scope=https://www.googleapis.com/auth/gmail.readonly https://www.googleapis.com/auth/userinfo.email
Once the user approves/declines, provider redirects the user to next step
(callback url) The Hosted Authentication Nylas Redirect URI where the provider
redirects back to. Used only for hosted authentication.
/connect/callback?code=...&state=...
Once the end user gets redirected to this URL by the provider, Nylas saves
tokens and creates a new grant. It then redirect back to the specified
redirect_uri requested to /connect/auth with the following query params:
https://myapp.com/callback-handler?
success=true // Whether the grant was successfully created
&grant_id=... // GUID grant identifier for your new integration
&state=... // Your passed state data
&provider=google // Provider type
&email=... // Email address (if integration/provider type and the requested scope allows)
If authentication fails success will be set to false:
https://myapp.com/callback-handler?
success=false // Meaning the authentication failed
&error=... // Error code
AUTHORIZATIONS:
BasicAuthBearerAuth
REQUEST BODY SCHEMA: APPLICATION/JSON
provider
required
string
Enum: "google" "microsoft" "imap"
Oauth provider
redirect_uri
required
string <url>
Developer redirect_uri for the final redirect. This should be one of the allowed
redirect_uris that's been previously set for this integration.
settings
object
Extra authentication settings. For example for IMAP you can specify the IMAP
provider to improve the user experience with an interface similar to official
Yahoo sign-in page
scope
Array of strings
If not specified it will use the integration default scopes. See Setting Scopes
for more.
grant_id
string
Optional existing grant_id to trigger a re-authentication. This might be useful
if you'd like to change the scopes of an existing grant or force a reauth for an
end-user.
login_hint
string
If provider supports this option, it will use it simplify the login flow.
state
string
Optional state value to return to developer's website after authentication flow
is completed
expires_in
integer <int32> >= 60
Default: 43200
How long this request and the attached login ID will remain valid before the
link expires. Defaults to 12 hours (43,200 seconds)
cookie_nonce
string
Optional cookie nonce that if provided, during the redirect of hosted
authentication Nylas will check if cookie exists in the white-labeled domain
origin. The cookie key should be x-cookie-nonce and value set to the same value
here in cookie_nonce field. Note that this feature is only usable if the
developer owns a white-labeled domain experience.
RESPONSES
200
401
404
post/connect/auth
Application
https://{{app-name}}.us.nylas.com/connect/auth
REQUEST SAMPLES
* Payload
Content type
application/json
Copy
Expand all Collapse all
{
* "provider": "google",
* "redirect_uri": "https://myapp.com/callback-handler",
* "settings": {
* "type": "yahoo"
},
* "scope": [
* "Mail.Read",
* "User.Read",
* "offline_access"
],
* "grant_id": "295bb5e9-c3ba-44b4-9467-11cb9867d1ce",
* "login_hint": "email@hotmail.com",
* "state": "my-state",
* "expires_in": 43200,
* "cookie_nonce": "e96bf6686a3c3510e"
}
RESPONSE SAMPLES
* 200
* 401
* 404
Content type
application/json
Copy
Expand all Collapse all
{
* "success": true,
* "data": {
* "url": "https://accounts.nylas.com/connect/login?id=BA630DED06...",
* "id": "BA630DED06...",
* "expires_at": 0,
* "request": {
* "redirect_uri": "https://myapp.com/callback-handler",
* "provider": "google",
* "scope": [
* "user:read",
* "user:write"
],
* "login_hint": "email@hotmail.com",
* "state": "my-state"
}
}
}
NATIVE AUTHENTICATION
Manually create grant for a native authentication. If you are handling the OAuth
flow in your own application or want to migrate existing users, Native
Authentication allows you to simply provide the user refresh_token in order to
create a grant.
AUTHORIZATIONS:
BasicAuth
REQUEST BODY SCHEMA: APPLICATION/JSON
One of
Refresh TokenCredential OverrideApp Permission MicrosoftApp Permission
GoogleIMAP
provider
required
string
Enum: "google" "microsoft"
Oauth provider
settings
required
object
Settings required by provider. Here is added "refresh_token" attribute with its
value.
scope
Array of strings
If not specified it will use the integration default scopes. See Setting Scopes
for more.
state
string
Optional state value to return to developer's website after authentication flow
is completed
RESPONSES
201
Grant Created
400
Bad Request
401
Not Authenticated
post/connect/grants
Application
https://{{app-name}}.us.nylas.com/connect/grants
REQUEST SAMPLES
* Payload
Content type
application/json
Example
Refresh TokenCredential OverrideApp Permission MicrosoftApp Permission
GoogleIMAPRefresh Token
Copy
Expand all Collapse all
{
* "provider": "google",
* "settings": {
* "refresh_token": "1//09XpDHQ6hq6PrCgYIARAAGAkSNwF..."
},
* "scope": [
* "Mail.Read",
* "User.Read",
* "offline_access"
],
* "state": "my-state"
}
RESPONSE SAMPLES
* 201
* 400
* 401
Content type
application/json
Copy
Expand all Collapse all
{
* "success": true,
* "data": {
* "id": "e19f8e1a-eb1c-41c0-b6a6-d2e59daf7f47",
* "provider": "google",
* "grant_status": "valid",
* "email": "email@hotmail.com",
* "scope": [
* "Mail.Read",
* "User.Read",
* "offline_access"
],
* "user_agent": "string",
* "ip": "string",
* "state": "my-state",
* "created_at": 1617817109,
* "updated_at": 1617817109,
* "provider_user_id": "b16f171c-6640-4edd-a598-e507b546d841"
}
}
CREDENTIALS
CRUD operations for management of credentials. This includes creating, getting,
finding, patching and deleting credential records. Credentials are used, for
example, to store provider's data for some specific use case (such as
client_id/client_secret different than integration's ones). Then this Credential
record can be used to create specific Grant via Native Authentication.
CREATE CREDENTIAL
Manually create a new credential record.
AUTHORIZATIONS:
BasicAuth
PATH PARAMETERS
provider
required
any
Example: google
REQUEST BODY SCHEMA: APPLICATION/JSON
name
required
string
Unique name of this credential
credential_type
required
string
Enum: "adminconsent" "serviceaccount" "integration"
Define type of this credential for App Permission flow ("adminconsent" for
Microsoft, "serviceaccount" for Google), or type of credential that can replace
default integration's information ("integration")
credential_data
required
object
Data that specifies some special data required for this credential. This data is
securely encoded and stored, and never again visible to end-user! Important ->
for App Permission Google this is required and must contain "private_key_id",
"private_key" and "client_email" at least. For App Permission Microsoft this is
required and must contain "client_id" and "client_secret" at least. For
Integration Override it must contain "client_id" and "client_secret" at least.
RESPONSES
201
Credential Created
400
Bad Request
401
Not Authenticated
post/connect/integrations/:provider/creds
Application
https://{{app-name}}.us.nylas.com/connect/integrations/:provider/creds
REQUEST SAMPLES
* Payload
Content type
application/json
Copy
Expand all Collapse all
{
* "name": "My first Google credential",
* "credential_type": "serviceaccount",
* "credential_data": {
* "type": "service_account",
* "project_id": "marketplace-sa-test",
* "private_key_id": "abcd1234defg5678",
* "private_key": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE
KEY-----\n",
* "client_email": "some-name@marketplace-sa-test.iam.gserviceaccount.com",
* "client_id": "123456789",
* "auth_uri": "https://accounts.google.com/o/oauth2/auth",
* "token_uri": "https://oauth2.googleapis.com/token",
* "auth_provider_x509_cert_url":
"https://www.googleapis.com/oauth2/v1/certs",
* "client_x509_cert_url":
"https://www.googleapis.com/robot/v1/metadata/x509/some-name%40marketplace-sa-test.iam.gserviceaccount.com"
}
}
RESPONSE SAMPLES
* 201
* 400
* 401
Content type
application/json
Copy
Expand all Collapse all
{
* "success": true,
* "data": {
* "id": "e19f8e1a-eb1c-41c0-b6a6-d2e59daf7f47",
* "integration_id": "d1n4M0ZG-ac12-13ab-98ed-1fe33cbd43a1",
* "name": "My first Google credential",
* "created_at": 1617817109,
* "updated_at": 1617817109
}
}
LIST CREDENTIALS
Lists credentials for given provider
AUTHORIZATIONS:
BasicAuth
PATH PARAMETERS
provider
required
any
Example: google
QUERY PARAMETERS
limit
integer
Default: 10
Limit the number of results
offset
integer
Default: 0
Offset results
sort_by
string
Default: "created_at"
Enum: "created_at" "updated_at"
Sort entries by field name
order_by
string
Default: "desc"
Enum: "desc" "asc"
Specify ascending or descending order
RESPONSES
200
Returns array of Credential objects
401
Not Authenticated
404
Not Found
get/connect/integrations/:provider/creds
Application
https://{{app-name}}.us.nylas.com/connect/integrations/:provider/creds
RESPONSE SAMPLES
* 200
* 401
* 404
Content type
application/json
Copy
Expand all Collapse all
{
* "data": [
* {
* "id": "e19f8e1a-eb1c-41c0-b6a6-d2e59daf7f47",
* "integration_id": "d1n4M0ZG-ac12-13ab-98ed-1fe33cbd43a1",
* "name": "My first Google credential",
* "created_at": 1617817109,
* "updated_at": 1617817109
}
],
* "limit": 10,
* "offset": 0
}
GET CREDENTIAL BY ID
Get credential by specified ID
AUTHORIZATIONS:
BasicAuth
PATH PARAMETERS
provider
required
any
Example: google
id
required
any
Example: e19f8e1a-eb1c-41c0-b6a6-d2e59daf7f47
RESPONSES
200
Returns Credential object
400
Bad Request
401
Not Authenticated
get/connect/integrations/:provider/creds/:id
Application
https://{{app-name}}.us.nylas.com/connect/integrations/:provider/creds/:id
RESPONSE SAMPLES
* 200
* 400
* 401
Content type
application/json
Copy
Expand all Collapse all
{
* "success": true,
* "data": {
* "id": "e19f8e1a-eb1c-41c0-b6a6-d2e59daf7f47",
* "integration_id": "d1n4M0ZG-ac12-13ab-98ed-1fe33cbd43a1",
* "name": "My first Google credential",
* "created_at": 1617817109,
* "updated_at": 1617817109
}
}
UPDATE CREDENTIAL BY ID
Patch credential by specified ID
AUTHORIZATIONS:
BasicAuth
PATH PARAMETERS
provider
required
any
Example: google
id
required
any
Example: e19f8e1a-eb1c-41c0-b6a6-d2e59daf7f47
REQUEST BODY SCHEMA: APPLICATION/JSON
name
string
Name of this credential
credential_data
object
Data that specifies some special data required for this credential. This data is
securely encoded and stored, and never again visible to end-user! Important ->
for App Permission Google this is required and must contain "private_key_id",
"private_key" and "client_email" at least. For App Permission Microsoft this is
required and must contain "client_id" and "client_secret" at least. For
Integration Override it must contain "client_id" and "client_secret" at least.
RESPONSES
200
Returns updated Credential object
400
Bad Request
401
Not Authenticated
patch/connect/integrations/:provider/creds/:id
Application
https://{{app-name}}.us.nylas.com/connect/integrations/:provider/creds/:id
REQUEST SAMPLES
* Payload
Content type
application/json
Copy
Expand all Collapse all
{
* "name": "My first Google credential",
* "credential_data": {
* "type": "service_account",
* "project_id": "marketplace-sa-test",
* "private_key_id": "abcd1234defg5678",
* "private_key": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE
KEY-----\n",
* "client_email": "some-name@marketplace-sa-test.iam.gserviceaccount.com",
* "client_id": "123456789",
* "auth_uri": "https://accounts.google.com/o/oauth2/auth",
* "token_uri": "https://oauth2.googleapis.com/token",
* "auth_provider_x509_cert_url":
"https://www.googleapis.com/oauth2/v1/certs",
* "client_x509_cert_url":
"https://www.googleapis.com/robot/v1/metadata/x509/some-name%40marketplace-sa-test.iam.gserviceaccount.com"
}
}
RESPONSE SAMPLES
* 200
* 400
* 401
Content type
application/json
Copy
Expand all Collapse all
{
* "success": true,
* "data": {
* "id": "e19f8e1a-eb1c-41c0-b6a6-d2e59daf7f47",
* "integration_id": "d1n4M0ZG-ac12-13ab-98ed-1fe33cbd43a1",
* "name": "My first Google credential",
* "created_at": 1617817109,
* "updated_at": 1617817109
}
}
DELETE CREDENTIAL BY ID
Delete credential by specified ID
AUTHORIZATIONS:
BasicAuth
PATH PARAMETERS
provider
required
any
Example: google
id
required
any
Example: e19f8e1a-eb1c-41c0-b6a6-d2e59daf7f47
RESPONSES
200
Delete Credential from database
400
Bad Request
401
Not Authenticated
delete/connect/integrations/:provider/creds/:id
Application
https://{{app-name}}.us.nylas.com/connect/integrations/:provider/creds/:id
RESPONSE SAMPLES
* 200
* 400
* 401
Content type
application/json
Copy
{
* "success": true
}
EVENT CODES
CATEGORIES
* HTTP: General purpose http response errors.
* Token: Events related to JWT tokens.
* Grant: Issues with a grant during creation (hosted, native) or maintenance.
* Integration: Events with integration.
* Provider: Problems that are reported from the provider's side and are out of
UAS control.
CODES
* 0000-9999: HTTP category
* 10000-19999: Token category
* 20000-29999: Grant category
* 30000-39999: Integration category
* 40000-49999: Provider category
PUB/SUB SAMPLE MESSAGE
{
"code": 25009,
"type": "grant_expired",
"level": "error",
"message": "Grant refresh/access token has expired, please re-auth. Marked as invalid grant",
"data": {
"integration_id": "3b970002-2b30-48da-9ff6-767af0089e57",
"grant_id": "1c5cc1c3-cffe-4a02-8794-a9c6808ab235",
"provider": "google"
},
"log_id": "ab2e318d-250d-4080-b871-e663ba9cdc1f",
"request_id": "aa2e318d-250d-4080-b871-e663ba9cdc1f",
"time": 1621981699
}
HTTP ERROR RESPONSE SAMPLE
{
"success": false,
"error": {
"type": "app_id_not_allowed",
"http_code": 400,
"event_code": 702,
"message": "Application ID not allowed",
"request_id": "e19f8e1a-eb1c-41c0-b6a6-d2e59daf7f47"
}
}
EVENT CODES
Type Code HTTP Code Default message Category bad_request 400 400 Bad request
HTTP invalid_request_error 401 401 Authentication error HTTP unauthorized_access
403 403 Unauthorized access HTTP not_found_error 404 404 Resource not found HTTP
internal_error 500 500 Internal error, contact administrator HTTP
invalid_request_payload 700 400 Invalid JSON payload format HTTP
invalid_query_params 701 400 Invalid query params provided HTTP
app_id_not_allowed 702 400 Application ID not allowed HTTP invalid_token_expiry
15001 400 Invalid expires_in value, should be integer in seconds, minimum 60secs
and maximum 10 years Token login_expires_in_invalid 25002 400 expires_in should
be more than one minute and less than 24 hours Grant redirect_uri_not_allowed
25003 400 redirect_uri is not allowed for this integration Grant
login_id_invalid 25004 400 Login ID or request is invalid or has expired Grant
integration_no_longer_exists 25005 400 Integration no longer exists Grant
no_login_scopes 25006 400 Integration default scopes and login request scopes
are both empty Grant grant_not_found 25007 404 Grant not found Grant
refresh_token_invalid 25008 400 Invalid refresh_token supplied to grant Grant
grant_expired 25009 N/A Grant refresh/access token has expired, please re-auth.
Marked as invalid grant Grant provider_required 25010 400 Provider field is
required Grant refresh_token_required 25011 400 refresh_token field is required
Grant grant_created 25012 201 Grant created Grant grant_deleted 25013 200 Grant
deleted Grant grant_updated 25014 200 Grant updated Grant reauth_email_invalid
25015 N/A Emails did not match during reauth Grant scopes_conflict 25016 N/A
Some requested scopes were NOT included in the completed hosted auth, resulting
in denied authentication Grant gmail_domain_invalid 25017 N/A GMail domain is
not allowed, resulting in denied authentication Grant grant_access_denied 25018
N/A Access to grant denied Grant historic_sync_completed 25020 N/A Historic sync
completed Grant invalid_authentication 25021 N/A Authentication failed due to
wrong input or credentials Grant provider_not_responding 25022 N/A Provider not
responding Grant auth_limit_reached 25023 N/A Max number of retries reached for
hosted authentication Grant grant_reauthenticated 25027 N/A Existing Grant
re-authenticated Grant hosted_login_started 26001 N/A Hosted login started.
Occurs when user visits "/connect/login?id=..." Grant hosted_login_used 26002
N/A Hosted login used. Happens when user gets redirected to Nylas'
"/connect/callback" Grant session_revoke_failed 26004 400 Session revoke failed
Grant session_revoke_success 26005 N/A Session revoke success Grant
integration_created 31001 201 Integration created Integration
integration_deleted 31002 200 Integration deleted Integration
integration_updated 31003 200 Integration updated Integration
integration_not_found 35004 404 Integration not found Integration
provider_not_supported 31005 400 Provider invalid or not supported Integration
provider_settings_invalid 35006 400 Provider settings not supported Integration
provider_settings_secret_required 35007 400 Provider settings and secret both
are required if one needs to change Integration integration_already_exists 35008
400 Integration already exists Integration integration_problem 35009 400 Issues
found with integration's settings/config Integration credential_not_found 35010
400 Credential not found Integration credential_already_exists 35011 400
Credential with this name for given integration already exists Integration
credential_missing_param 35012 400 Credential is missing some essential values
in its settings Integration credential_created 31013 201 Credential created
Integration credential_updated 31014 200 Credential updated Integration
credential_deleted 31015 200 Credential deleted Integration
provider_code_request_failed 45001 400 Provider refused to return refresh_token
using code (hosted auth) Provider oauth_failed 45002 400 Hosted OAuth failed due
to rejection by provider or user refusing consent Provider invalid_client 45003
400 The OAuth client was not found Provider invalid_grant 45004 400 Error
creating grant with provided OAuth params Grant invalid_request 45005 400 The
request is missing a required parameter, includes an invalid parameter value, or
is otherwise malformed HTTP redirect_uri_mismatch 45006 400 Redirect URI not
allowed Integration unsupported_grant_type 45007 400 Invalid grant_type Grant
invalid_token 45008 400 Token expired or revoked Token oauth_redirect 45009 N/A
Redirecting in OAuth2.0 protocol HTTP oauth_provider_error 45010 400 Error from
OAuth2 provider Provider