Manage accounts in Nylas v2
In Nylas v2, an account (or "connected account") represents an end user who is authenticated with your application using Nylas. This section describes how to manage your Nylas application's connected accounts, including when to restart, re-authenticate, and delete them.
📝 Nylas bills for all connected accounts unless their billing_state is cancelled or deleted. See the Billing documentation for more information.
How connected accounts work
When an end user authenticates with your Nylas application, Nylas begins tracking access tokens for their connected account, and object IDs for the account's associated data.
When an account's access token becomes invalid, Nylas stops syncing its data. You should monitor accounts for stopped or invalid states, and prompt the user to re-authenticate when you detect one. You might need to re-authenticate an account because of normal events like password changes or errors. This is part of the normal lifecycle for connected tools, and you should plan to handle it gracefully. If an account is not re-authenticated when it stops syncing, you not longer have access to that account's data, and you won't get notifications about changes to its data.
As part of your Nylas application's user billing cycle, you might want to temporarily stop a connected account syncing (for example, if their subscription to your service expires). You can also delete connected accounts.
Account lifecycle
Your end users' accounts connect to your app using Nylas, and Nylas syncs their data. When they first connect, their account might be in the Partial state while Nylas syncs their data — especially if they have a lot to sync.
When the initial historical sync finishes, the account changes to the Running state. Connected accounts might re-enter the Partial state if they experience latency or other issues.
🔍 If an account enters the Partial state often or stays in the Partial state for a long time, contact Nylas Support for troubleshooting help.
If a connected account has problems with authentication, it might move to the Invalid state. This can usually be fixed by having the end user re-authenticate their account.
If Nylas encounters too many errors when trying to connect an account, even after many retries, the account status might change to Stopped. In this case, contact Nylas Support for troubleshooting help.
The diagram below shows how an account might change states through its lifecycle.
Manage access tokens
The following sections explain how to generate and revoke access tokens for connected accounts.
Connected accounts' <ACCESS_TOKENS> never expire in Nylas API v2. If you want to stop using an access token, or prevent others from using it, you must revoke it. You should also revoke any previous access tokens when an end user re-authenticates their account.
Though they never expire, access tokens can become invalid or need re-authentication (for example, when an end user changes their password). In this case, you can generate an access token for their account, then revoke their old token.
Generate access tokens in Nylas Dashboard
You can generate access tokens in the Nylas Dashboard. To do this, select Accounts from the left navigation menu. On the Accounts page, choose the connected account that you want to generate a token for, and click Generate a new token.
Generating an access token does not delete previous access tokens. See the Revoke access tokens section for more information.
Revoke access tokens
To revoke a connected account's access tokens, make a POST /a/{client_id}/accounts/{id}/revoke-all request and include the keep_access_token body parameter.
⚠️ Gmail limitation: If you make a Revoke All request and omit the keep_access_token parameter, the Gmail refresh_token is also revoked.
The following workflow is an example of when a connected account's access tokens should be revoked, and how to do so.
- Authenticate a Google account and get its
<ACCESS_TOKEN>. - The end user changes their password and their connected account becomes invalidated, but their
<ACCESS_TOKEN>is still active. - Re-authenticate the Google account and receive a new
<ACCESS_TOKEN>. - Make a request to the Revoke All endpoint with
keep_access_token=<ACCESS_TOKEN>, using the new access token from step 3.
Delete a connected account
When you need to delete connected accounts from your Nylas application, you can either delete them immediately or downgrade and cancel them.
Immediately delete a connected account
To delete a connected account immediately, make a DELETE /a/{client_id}/accounts/{id} request. After you make a Delete Account request, you cannot upgrade the account, access its data, or do anything else with it.
When you make the DELETE request, the affected account's data is queued for deletion. Nylas deletes the data within three days. The following changes also occur automatically:
- The account is no longer counted for billing.
- The account's data stops syncing.
- Nylas no longer sends webhook notifications for the account.
- The account's previously synced data is no longer available, even if the user re-authenticates. Nylas must completely sync their data again.
Downgrade and cancel a connected account
If you prefer more flexible timing before making a connected account unavailable, you can first revoke its access tokens, then downgrade it. Revoking an account's access tokens removes the end user's access to your Nylas application, but doesn't delete the account.
After you downgrade an account, Nylas queues it to be deleted within three days. If you need to re-activate the account during that time, you can still update it.
💡 If you need confirmation that an account is deleted within the three day timeframe, contact Nylas Support and request a GDPR deletion.
If the end user re-authenticates a downgraded account within three days of its status change, Nylas does not delete the account.
For more information, see the Revoke all tokens and Cancel an account documentation.