Docs / Flows
Deleting a workspace or an account
How owners, staff and members delete a workspace or an account, what is removed at once, what is kept for credit-law retention, and how legal holds work.
Rules and sources: docs/data/deletion-and-retention.md (developer docs, not legal advice).
Who can do what#
| Action | Endpoint | Who |
|---|---|---|
| See what deleting would do, with the export links | GET /account/organization/deletion-preview | the Owner of the active workspace (business.delete) |
| Delete the workspace | POST /account/organization/delete | the Owner; body { confirmName, exportAcknowledged: true }; confirmName is the exact workspace name |
| Delete any workspace | POST /internal/tenants/:id/delete | staff with staff.tenants.delete, same body, never during a support session |
| Delete an account | POST /auth/delete-account (emailed code) | the person; refused while they own a workspace |
| Delete any account | POST /internal/users/:id/delete | staff with staff.users.delete; body { confirmEmail, exportAcknowledged: true }; never staff accounts, never an Owner |
| Set or release a legal hold | POST /internal/legal-holds | staff with staff.legal_hold.manage; body { targetType: "Organization" or "Application", targetId, hold, reason } |
| List deletions, read one, retry a failed one | GET /internal/deletions, GET /internal/deletions/:id, POST /internal/deletions/:id/retry | staff with staff.retention.view (retry: staff.tenants.delete) |
What happens#
- At once: every member loses access, sessions are revoked, connectors stop, the identities of people with no other workspace are replaced, the workspace becomes a tombstone, and the retention clock is set on every application. The response returns a request id and counts.
- Within minutes (queue): the WorkOS users, memberships, SSO connections, domains and organization are deleted. A provider outage is retried for about three hours, then the request is
FAILEDwith an audit event; staff retry it. - Then and daily: the working copy of the applications is pseudonymized (not while a hold is set); after the retention period (default 25 months,
RETENTION_MONTHS, never below 12) stored files are deleted and the personal data of the sealed signed records is overwritten. A legal hold on the organization or the application stops this.
Drafts that were never submitted (including a person's saved application drafts) have no retention duty and are purged at once. Audit events are never deleted.
Errors#
| Status | Meaning |
|---|---|
| 400 | typed name or email does not match, or the export was not acknowledged |
| 403 | not the Owner, not staff, a support session, or an Owner trying to delete their own account |
| 404 | unknown workspace, account, application or request |
| 409 | already deleted, a workspace owner cannot be deleted directly, a request is not FAILED |
| 429 | too many attempts |