Deleting a Nylas resource affects everything beneath it. Because grants depend on the connector, credential, and workspace they belong to, removing one of those parent resources can invalidate grants and queue their data for deletion. This page explains what each deletion does, what it cascades to, and when the data is permanently gone.
How Nylas resources are organized
Section titled “How Nylas resources are organized”Nylas arranges your data into five resource types that form a hierarchy. An application is the top level. Beneath it sit connectors (one per provider), connector credentials (which belong to a connector), and workspaces (which group grants). A grant represents one authenticated user account and sits at the bottom, tied to both a connector and a workspace.
Deletions flow downward. When you delete a parent, the deletion acts on the children that depend on it: a grant can’t keep working if the connector or credential it authenticates through is gone. Only the application is deleted exclusively from the Nylas Dashboard; connectors, credentials, and workspaces each have a public delete endpoint.
What gets deleted at each level
Section titled “What gets deleted at each level”The table below summarizes the four delete operations. “Invalidated” means the grant stops working right away but its record still exists for a short time; “removed” means the record is permanently deleted after a grace period.
| You delete | Invalidated immediately | Removed after a grace period | You cannot delete |
|---|---|---|---|
| Connector | All grants on the connector | The connector, its credentials, and the invalidated grants | None |
| Connector credential | Grants that authenticate through it | The credential, plus its grants when the connector is cleaned up | The connector’s default (active) credential |
| Workspace | None (grants are re-homed) | The workspace record | The application’s default workspace |
| Application (Dashboard only) | All grants in the application | The application and every connector, credential, workspace, and grant under it | None |
What happens when you delete a connector
Section titled “What happens when you delete a connector”Deleting a connector invalidates every grant that authenticates through it. Those grants stop working straight away because the provider settings Nylas needs to refresh their tokens are gone. The grant records, the connector, and the connector’s credentials are then permanently removed together after a grace period, so a single delete can affect hundreds of grants at once.
Use the Delete connector endpoint to remove a connector. If you only need to disconnect individual users, delete their grants instead and leave the connector in place.
What happens when you delete a credential
Section titled “What happens when you delete a credential”Deleting a non-default connector credential removes that one credential and invalidates the grants that authenticate through it. The grants stop working immediately, and their records are permanently deleted when the connector is later cleaned up. You can’t delete a connector’s default (active) credential on its own; it’s removed only when you delete the connector itself.
See the Delete credential endpoint for the request. Each connector keeps exactly one default credential, which is the one Nylas uses unless you override it.
What happens when you delete a workspace
Section titled “What happens when you delete a workspace”Deleting a workspace is a soft delete that doesn’t invalidate any grants. Nylas re-homes the workspace’s grants to the application’s default workspace if one exists, or leaves them unassigned if there’s no default. The grants keep working throughout. Only the workspace record is removed, and that happens after a grace period rather than instantly.
You can’t delete the application’s default workspace. See the Delete workspace endpoint and the workspaces overview for how grouping and default assignment work.
What happens when you delete an application
Section titled “What happens when you delete an application”Deleting an application removes everything under it: all four lower resource types (connectors, credentials, workspaces, and grants), along with the data synced for those grants. This is the broadest deletion available, and you perform it from the Nylas Dashboard rather than through the API. There’s no public endpoint for application deletion.
To remove an application and all associated data for a “right to be forgotten” request, see the GDPR overview. For ongoing work, prefer deleting individual grants or connectors over the whole application.
Delete a single user’s data
Section titled “Delete a single user’s data”To remove one user’s data without touching the rest of your application, delete their grant. A Delete Grant request revokes the associated provider tokens, stops all notifications for that user, and removes the grant. This is the right tool for honoring an individual data-deletion request from one of your users.
Deleting a grant is irreversible. If the same user reconnects later, Nylas creates a new grant with a new ID, so don’t delete grants you intend to recover. For the difference between deleting and re-authenticating an expired grant, see handling expired grants.
When is deleted data permanently removed?
Section titled “When is deleted data permanently removed?”Deletion happens in two stages. First, the resource is invalidated or soft-deleted immediately, so it stops working the moment your request succeeds. Second, the underlying records are permanently deleted after a grace period during which they no longer function but still exist in Nylas storage. The exact retention window is an internal operational detail and isn’t guaranteed.
If you need data removed within a specific timeframe for a compliance request, contact Nylas Support rather than relying on the standard cleanup. Support can also export your data in a machine-readable format, as described in the GDPR overview.
What’s next
Section titled “What’s next”- Delete connector, Delete credential, and Delete workspace endpoint references
- Delete Grant for removing a single user
- GDPR overview and inquiries for data portability and right-to-be-forgotten requests
- Handling expired grants for why you should re-authenticate instead of deleting
- Data residency for where your data is stored