Workspaces
Summary
A workspace is one brand, client or business inside an organization. It has its own files, folders, tags, statuses and fields and its own members. The work happens in a workspace: you always open one to see files.
An organization has at least one workspace and can have as many as it needs. Owners and admins of the organization reach all of them. Members reach only the workspaces they are added to.
A workspace can be deleted. It then disappears for everyone at once, stays restorable for 30 days, and is removed for good after that.
This page covers creating, renaming, who reaches a workspace, workspace membership, deleting, restoring and the rule that an organization keeps at least one workspace. What a workspace's files can do is described under Files & Assets.
Who can do what
"Organization role" is the member's role in the organization. "Effective workspace role" is the stronger of that role (when it is owner or admin) and the member's role in the workspace. See Members and roles.
| Action | Who | Verified email | Session | Credential (scope) |
|---|---|---|---|---|
| List the workspaces you reach | Everyone, for their own | No | Yes | Yes (any scope) |
| Open a workspace | Organization owners and admins; workspace members | No | Yes | Yes, for its own workspaces |
| List a workspace's members | Everyone who can open it | No | Yes | Yes (workspace:read) |
| Create a workspace | Organization owner or admin | No | Yes | No |
| Rename a workspace | Effective workspace owner or admin | No | Yes | No |
| Add a member to a workspace, or change their workspace role | Effective workspace owner or admin | No | Yes | No |
| Give or take away the workspace role owner | Effective workspace owner | No | Yes | No |
| Remove a workspace membership | Effective workspace owner or admin | No | Yes | No |
| Delete a workspace | Organization owner or admin | Yes | Yes | No |
| List deleted workspaces | Organization owner or admin | No | Yes | No |
| Restore a deleted workspace | Organization owner or admin | No | Yes | No |
- A plain member who is admin or owner of one workspace can rename it and manage its members. They cannot create, delete or restore workspaces: those need the organization role.
- A credential that calls a session-only operation gets
403 FORBIDDENwithdetails.reasonSESSION_REQUIRED.
How it works
What a workspace holds
- Its files, with their versions, folders and tags.
- Its own file statuses and custom fields. A file of the workspace carries only the workspace's status and field values. See Statuses and Fields and tags.
- Its uploads and its suggestions. A workspace's suggestion names only that workspace's own files; the organization folder has its own.
- Its members: the workspace memberships.
- A workspace belongs to exactly one organization and cannot be moved to another.
- The organization folder is not part of any workspace. It has its own folders, tags, statuses and fields. See The organization folder and suggestions.
Creating
- Organization owners and admins create workspaces.
- A workspace needs a name. Nothing else is asked.
- A new workspace is empty: no files, no folders, no tags, no custom fields. It starts with three statuses of its own: "Approved for public use" (allows public use), "Internal use only" (the default for new uploads) and "Not approved".
- A new workspace has no workspace memberships. Its creator reaches it through their organization role, like every other owner and admin.
- Plain members do not see a new workspace until someone adds them to it.
- No email is sent when a workspace is created.
- The first workspace of an organization is created together with the organization. See Organizations.
- A workspace cannot be created in a deleted organization.
Naming rules
- A workspace name is 1 to 200 characters long.
- Spaces at the start and end are removed before the name is measured and stored.
- A name that is empty after trimming is refused.
- A name with a control character, such as a tab or a line break, is refused, also at the very end of the name.
- Any other character is allowed.
- A workspace name is unique within its organization, ignoring case. "Docs" and "DOCS" cannot both exist in one organization.
- Only live workspaces count. The name of a deleted workspace is free for a new workspace at once.
- Workspaces in different organizations can have the same name.
- Creating or renaming to a name that is taken answers
409 CONFLICT, reasonNAME_TAKEN.
Renaming
- A workspace is renamed by its effective owners and admins: organization owners and admins, and members who hold the workspace role owner or admin.
- The new name follows the naming rules above.
- A rename that only changes the case of the name is allowed: "Other" can become "OTHER".
- A rename takes effect at once for everyone.
- A rename does not change the workspace's ID, files, members, links or credentials.
- A deleted workspace cannot be renamed. Restore it first.
- If two people rename the same workspace at the same moment, both succeed and the later name stays.
- If two people give two workspaces the same name at the same moment, one
succeeds and the other gets
409 CONFLICT, reasonNAME_TAKEN.
Who reaches which workspace
- Organization owners reach every workspace, as owner.
- Organization admins reach every workspace, as admin at least.
- Members reach the workspaces they have a workspace membership for, with the role of that membership.
- Nobody else reaches a workspace. Someone without access gets
404 NOT_FOUND, the same answer as for a workspace that does not exist. - A credential reaches the workspaces it was given, and only while its member can still open them. See Credentials and scopes.
- Reaching a workspace means reading everything in it and working with its files. What exactly each role may do with files is in Roles and permissions.
- The workspace chosen in the app is a convenience. It never grants access.
- A file shared publicly can be opened by anyone with its link, without reaching the workspace. See Sharing and public links.
Workspace membership
- A workspace membership gives one organization member a role in one
workspace:
owner,adminormember. - Only members of the organization can be added. To add someone new, invite them to the organization first; an invitation can name the workspaces they join. See Invitations.
- A member can belong to any number of workspaces, with a different role in each.
- Effective workspace owners and admins add members, change workspace roles and remove workspace memberships.
- Only an effective workspace owner gives the workspace role owner, changes the role of a workspace owner or removes a workspace owner's membership.
- Adding someone who is already a workspace member with the same role succeeds and changes nothing.
- Adding someone who is already a workspace member with another role changes their role.
- An organization owner or admin can also be given a workspace membership. It makes no difference while they hold that organization role. It decides what they keep if they are later made a plain member.
- Removing a workspace membership ends that member's access to the workspace at once, unless they are an organization owner or admin: those keep reaching it through their organization role.
- Only a workspace membership can be removed. Access that comes from an organization role is changed by changing the organization role.
- Removing a workspace membership does not remove the person from the organization or from their other workspaces.
- A plain workspace member cannot remove their own membership. There is no "leave workspace". An owner or admin removes them, or they leave the whole organization.
- An API key or connected app that named the workspace stops reaching it when its member loses access. The credential itself is not revoked. If the member is added again, it reaches the workspace again.
- Files the member uploaded stay.
- No email is sent when someone is added to or removed from a workspace.
- The workspace member list shows everyone who can open the workspace: the
workspace members and the organization's owners and admins. Each entry has
the effective role and a
source:workspacefor a workspace membership,organizationfor access through the organization role.
Deleting a workspace
- Organization owners and admins delete workspaces. The organization role is what counts: a member who is owner of only that workspace cannot delete it.
- The person deleting must have a verified email address.
- The request must repeat the workspace's name exactly as it is, in
confirmName. The comparison is exact: case and spaces count. - The organization's only live workspace cannot be deleted. See The last-workspace rule.
- The answer is
202with the workspace's ID, name,deletedAtandpurgeAfter.purgeAfteris 30 days afterdeletedAt.
The checks happen in this order. The first that fails decides the answer:
- Not signed in:
401 UNAUTHENTICATED. - The workspace is unknown or already deleted, its organization is deleted,
or you cannot open the workspace:
404 NOT_FOUND. - You can open the workspace but are a plain member of the organization:
403 FORBIDDEN. - Your email is not verified:
403 EMAIL_NOT_VERIFIED. confirmNameis not the workspace's name:422 VALIDATION_FAILEDonconfirmName.- It is the organization's only live workspace:
409 CONFLICTwithdetails.reasonLAST_WORKSPACE. - Otherwise it is deleted:
202.
What deletion does at once
A deleted workspace is hidden, not destroyed. From the moment of deletion:
- Nobody can open it: not its members, not owners or admins, not
credentials. Every request for it or anything in it answers
404 NOT_FOUND. - It leaves every list: the workspace switcher, your workspaces, the organization's workspaces and the organization's workspace count.
- Its files stop counting: files elsewhere no longer name them as duplicates. Its statuses, fields and tags are out of reach with it and come back unchanged with a restore.
- Public links to its files stop working. They answer "not found".
- Signed download links and archive links made before the deletion stop working.
- API keys and connected apps that named it no longer list it or reach it. Their other workspaces keep working.
- A new API key cannot name it.
- Pending invitations no longer list it, and their emails no longer name it. A new invitation cannot name it.
- An invitation accepted while it is deleted does not add the person to it.
- Exports started from now on leave it out, with everything in it.
- Its name is free. A new workspace can take it.
Nothing is thrown away yet. These are kept for a restore:
- every file, version, folder and tag, and its statuses and fields,
- every workspace membership and its role,
- the place it has in pending invitations,
- the place it has in API keys and connected apps,
- every public link address.
No email is sent when a workspace is deleted.
The 30-day restore window
- A deleted workspace can be restored for 30 days.
- The deadline is
purgeAfter. It is fixed at the moment of deletion and never shorter than 30 days. - Until the deadline, organization owners and admins see the workspace in the list of deleted workspaces, most recently deleted first, with the date it was deleted and the date it is removed for good.
- Members do not see deleted workspaces.
- At the deadline the workspace can no longer be restored and leaves the deleted list, whether or not it has been removed yet.
- Shortly after the deadline it is removed for good: the workspace, its memberships, its files with all their versions and stored content, its folders, tags, statuses, fields and uploads. Invitations and credentials that named it stay but no longer name it.
- Removal for good cannot be undone.
- Deleting the whole organization inside the window does not extend it. See Deleting and restoring.
Restoring
- Organization owners and admins restore a deleted workspace until its deadline. A verified email is not needed.
- A restore brings the workspace back whole, as it was:
- the same ID and name,
- every file, version, folder and tag, and its statuses and fields,
- every workspace membership with its role,
- its place in pending invitations,
- its place in API keys and connected apps, which reach it again,
- the same public link addresses, which work again.
- Signed download links made before the deletion work again too, until they expire on their own.
- An upload that was still being checked when the workspace was deleted is finished in the background and is there after the restore.
- The answer is
200with the workspace and your effective role in it. - No email is sent.
The checks happen in this order:
- Not signed in:
401 UNAUTHENTICATED. - The workspace is unknown, not deleted or past its deadline, its
organization is deleted, or you are not an owner or admin of the
organization:
404 NOT_FOUND. Only owners and admins see a deleted workspace, so nobody else learns that there is one to restore. - A live workspace has its name, ignoring case:
409 CONFLICTwithdetails.reasonNAME_TAKEN. - Otherwise it is restored:
200.
Name conflicts on restore
- While a workspace is deleted, its name is free, so another workspace may have been created or renamed to it.
- A restore never renames anything by itself. It is refused with
409 CONFLICT, reasonNAME_TAKEN, and the message "A workspace has this name now; rename it, then restore this one". - The deleted workspace stays deleted and stays in the deleted list. Its deadline does not move.
- To resolve it, rename the live workspace that has the name, then restore again. The restored workspace comes back with its original name.
- A deleted workspace cannot be renamed, so the live one is the one to rename.
- Two deleted workspaces can have the same name. Only one of them can be restored while it keeps that name; the other needs the first renamed.
The last-workspace rule
- An organization keeps at least one live workspace.
- Deleting the only live workspace is refused with
409 CONFLICT, reasonLAST_WORKSPACE, and the message "an organization keeps at least one workspace". - Deleted workspaces do not count as "another workspace".
- To replace the only workspace, create the new one first, then delete the old one.
- The rule holds when two people act at once. If an organization has two workspaces and two admins each delete one at the same moment, one deletion succeeds and the other is refused.
- To get rid of everything, delete the organization instead.
When a workspace you have open is deleted
- Your next action in it is refused.
- The app says "You no longer have access to {workspace}" and takes you to another workspace you can reach.
- If you can reach no other workspace, you land on "No workspace yet".
- The workspace is gone from your switcher.
- The same happens when you are removed from a workspace you have open.
What a workspace does not have
- A workspace cannot be duplicated or copied.
- A workspace is live or deleted. There is no archived and no read-only state.
- A workspace has a name and nothing else to describe it: no description, no color and no picture.
In the app
The workspace switcher
The switcher is at the top of the sidebar.
- It lists every workspace you can open, grouped under the name of its organization.
- Choosing one opens it and remembers it as your last used workspace.
- With no workspace open it reads "Choose a workspace", or "No workspace" when you have none.
- "New workspace" is offered to owners and admins of the current organization. It opens the "New workspace" dialog and then opens the new workspace.
- "Organization settings" opens the settings of the current organization.
- "Create organization" starts a new organization.
- The command palette offers "Switch to {workspace}" for each other workspace.
The Workspaces page
Settings > Organization > Workspaces has the section "Workspaces".
- For owners and admins it says "Every workspace of the organization. Its members reach only the workspaces they are added to." and lists every workspace.
- For members it says "The workspaces of this organization you can open." and lists only those.
- A member of no workspace reads "You are not a member of any workspace here yet. An owner or admin can add you to one."
- The table has the columns "Name" and "Your role", your effective role there. The name opens that workspace's settings page.
- Owners and admins also have "New workspace" above the list and "Deleted workspaces" below it.
The settings navigation
Below the organization's pages, the settings navigation has the group "File spaces": "Organization folder", then each workspace of the organization you can open. A member sees only the workspaces they are added to. An arrow at the end of each row says it opens a navigation of its own.
Choosing a workspace opens its settings page and swaps the navigation for the workspace's own level:
- "Back to settings" at the top, shown as "Back".
- The workspace's name as the heading.
- The group "Workspace" with "General", the workspace's settings page
(
/settings/organization/{organizationID}/workspaces/{workspaceID}). - The group "Files & Assets" with three pages:
- "Statuses", the workspace's file statuses
(
/settings/organization/{organizationID}/workspaces/{workspaceID}/files/statuses; see Statuses). - "Custom fields", its custom fields and their options
(
.../files/fields; see Fields and tags). - "Tags", its tags (
.../files/tags; see Managing tags).
- "Statuses", the workspace's file statuses
(
The page you are on is marked. Choosing "Organization folder" opens its
"Statuses" page and the organization folder's own level: "Back", "Organization
folder" as the heading, and only the group "Files & Assets" with the same
three pages, at
/settings/organization/{organizationID}/library/statuses, .../fields
and .../tags. Every member sees them; only the organization's owners and
admins change them.
-
The address without a page,
/settings/organization/{organizationID}/libraryor/settings/organization/{organizationID}/workspaces/{workspaceID}/files, opens the "Statuses" page. -
The workspace's navigation shows on every one of its pages, also when you open one by its address or from the Workspaces page.
-
"Back to settings" opens the organization's General page with the main navigation, and the keyboard focus lands on the workspace you came from.
-
Going in, the new navigation slides in from the right; going back, from the left. With reduced motion it fades in instead.
-
On a narrow screen the navigation opens in a sheet from the page title. Choosing a workspace or "Back to settings" there keeps the sheet open on the other navigation; choosing a page closes it.
A workspace's settings page
The page starts with the workspace's name and a line such as "Workspace in {organization} ยท Your role: Admin". Its statuses, custom fields and tags are on their own pages, "Statuses", "Custom fields" and "Tags" under "Files & Assets" in the workspace's settings navigation. The page has these sections, in this order:
- General. The workspace's name. See Renaming a workspace.
- Members. Everyone who can open the workspace. See Workspace members in the app.
- Delete workspace. Only for owners and admins of the organization, and not on the organization's only workspace. See Deleting a workspace in the app.
- A workspace has no other settings besides its statuses, fields and tags.
- The page works beside whatever workspace you have open. It does not switch the workspace you are working in.
- The address of a workspace that was deleted, or that you cannot open, shows "Workspace not found": "It was deleted, or you cannot open it." with the link "Workspaces of {organization}".
Creating a workspace
- Choose "New workspace" on the Workspaces page or in the workspace switcher.
- The dialog "New workspace" has the field "Workspace name" and the button "Create workspace".
- After creating, the app shows "{name} created". From the switcher it also opens the new workspace.
- A blank or too long name shows "Enter a name, up to 200 characters."
- A name another workspace has shows "Another workspace already has this name." under the field.
Renaming a workspace
- Open the workspace's settings page.
- In the section "General", change "Workspace name" and choose "Save". "Save" is disabled until the name differs from the current one.
- After saving, the app shows "Workspace renamed". The page, the settings navigation and the switcher show the new name without a reload.
- The same two messages as for creating apply.
- If you do not manage the workspace, the section shows the name and "Only owners and admins of the workspace can rename it." instead of the field.
Workspace members in the app
The section "Members" on a workspace's settings page says "Organization owners and admins reach every workspace. Others reach it through a workspace membership."
- The table "Members" has the columns "Name" (with "You" on your own row), "Role", such as "Admin", and "Access": "Through organization role" or "Workspace member".
- "Load more" shows further members.
- If you manage the workspace, rows with "Workspace member" that you may remove have a "Remove" button.
- If you manage the workspace, a form below the list adds a member:
- "Choose a member" lists the organization's members who do not reach the workspace yet.
- The role choice lists the roles you may give: "Member" and "Admin", and "Owner" if you are an owner there. It starts on "Member".
- "Add to workspace" adds them. The app shows "Added {name} to {workspace}".
- When everyone already reaches the workspace, the form is replaced by "Every organization member already reaches this workspace."
- "Remove" asks "Remove {name}?" with the text "They lose access to {workspace} at once. Files they uploaded stay." and the buttons "Cancel" and "Remove member". Afterwards the app shows "Removed {name} from {workspace}".
- If something fails the section says "Could not add the member. Try again." or "Could not remove the member. Try again."
- While the list loads the section says "Loading members". If it cannot be loaded it says "Could not load the members." with "Retry". If the people to add cannot be loaded it says "Could not load the organization's members." with "Retry".
- The section adds and removes. It does not change the role of someone who is already a workspace member; remove them and add them again with the other role.
Deleting a workspace in the app
- Open the workspace's settings page. The section "Delete workspace" says "Everyone loses access to it and its files at once. Owners and admins can restore it for 30 days."
- Choose "Delete workspace". The dialog "Delete {name}" says "Everyone loses access to it and its files at once. Owners and admins can restore it for 30 days; after that its files are deleted for good."
- Type the workspace's name into "Confirm workspace name". The hint reads
Type "{name}" to confirm. - The dialog's "Delete workspace" stays disabled until the name matches exactly.
- After deleting, the app shows "{name} deleted. Owners and admins can restore it until {date}." and opens the Workspaces page. The workspace leaves the list, the settings navigation and the switcher.
- A wrong name shows "Type the workspace's name exactly."
- If it is the last workspace the dialog says "An organization keeps at least one workspace."
- If your email is not verified, the "Delete workspace" button is disabled and the section says "Verify your email before deleting a workspace." If the refusal still happens, the dialog shows "Verify your email": "To delete this workspace, first open the link we sent to {address}." with "Resend verification email".
- A double click deletes once.
Restoring a workspace in the app
Owners and admins see "Deleted workspaces" below the list on the Workspaces page, as long as there is at least one.
- The table has the columns "Name", "Deleted" and "Deleted for good on", with the dates of the deletion and of the purge.
- "Restore" brings it back. The app shows "{name} restored", and the workspace returns to the list, the settings navigation and the switcher.
- If a live workspace has its name: "Another workspace is named {name} now. Rename that one, then restore this one."
- If it is no longer there to restore, because someone else restored it or its 30 days ended, the app reports no failure and reloads the lists. A workspace someone restored is under "Workspaces"; one past its 30 days is gone.
- For any other failure: "Could not restore the workspace. Try again."
- If the list cannot be loaded: "Could not load the deleted workspaces." with "Retry".
- Members are not shown "Deleted workspaces".
For agents
A credential can list the workspaces it reaches and read a workspace's members. Creating, renaming, deleting and restoring workspaces and changing their members need a person in a browser.
| Operation | Capability ID | MCP tool | Scope |
|---|---|---|---|
GET /v1/workspaces | workspaces.list | workspaces_list | any |
GET /v1/workspaces/{workspaceID}/members | workspaces.members.list | workspaces_members_list | workspace:read |
POST /v1/organizations/{organizationID}/workspaces | workspaces.create | none | session only |
PATCH /v1/workspaces/{workspaceID} | workspaces.update | none | session only |
DELETE /v1/workspaces/{workspaceID} | workspaces.delete | none | session only |
POST /v1/workspaces/{workspaceID}/restore | workspaces.restore | none | session only |
GET /v1/organizations/{organizationID}/deleted-workspaces | organizations.deleted_workspaces.list | none | session only |
PUT /v1/workspaces/{workspaceID}/members/{userID} | workspaces.members.put | none | session only |
DELETE /v1/workspaces/{workspaceID}/members/{userID} | workspaces.members.remove | none | session only |
Start with workspaces_list
Every task starts by asking which workspaces the credential reaches:
curl -s "$TALEWRIGHT/v1/workspaces" \
-H "Authorization: Bearer $TALEWRIGHT_API_KEY"
{
"items": [
{
"id": "01928f40-1111-7aaa-8bbb-000000000001",
"name": "Brand",
"organizationID": "01928f3e-7c1a-7d2b-9a41-3f0c2d9e8b17",
"organizationName": "Acme"
},
{
"id": "01928f40-2222-7aaa-8bbb-000000000002",
"name": "Campaigns",
"organizationID": "01928f3e-7c1a-7d2b-9a41-3f0c2d9e8b17",
"organizationName": "Acme"
}
]
}
-
Pass the chosen
idasworkspaceIDto the workspace tools. -
Pass
organizationIDto thelibrary_tools. -
A workspace that is missing here cannot be reached with this credential: it was not given to it, its member lost access, or it was deleted.
-
A deleted workspace comes back in this list after a restore, without any change to the credential.
-
No operation reads one workspace by its ID.
GET /v1/workspaceslists the workspaces the caller reaches, and reading the organization lists its workspaces./v1/workspaces/{workspaceID}takesPATCHandDELETEonly.
Reading a workspace's members
GET /v1/workspaces/{workspaceID}/members returns the people who can open
the workspace. The shape and paging are described in
Members and roles.
What the session-only operations take and return
| Operation | Body | Success |
|---|---|---|
| Create | {"name": "..."} | 201 with the workspace: id, name, organizationID, organizationName, role |
| Rename | {"name": "..."} | 200 with the workspace |
| Delete | {"confirmName": "..."} | 202 with id, name, deletedAt, purgeAfter |
| Restore | none | 200 with the workspace |
| List deleted | none | 200 with {"items": [{"id", "name", "deletedAt", "purgeAfter"}]} |
| Add or change a member | {"role": "owner" | "admin" | "member"} | 200 with the member and their effective role |
| Remove a member | none | 204 |
Edge cases
| Situation | What happens | Why |
|---|---|---|
| A workspace named "Docs" exists and someone creates "DOCS" | 409 CONFLICT, reason NAME_TAKEN. | Names are unique in the organization, ignoring case. |
| A workspace is renamed to another workspace's name in a different case | 409 CONFLICT, reason NAME_TAKEN. | Same rule. |
| A workspace is renamed to its own name in a different case | It works. | It conflicts with no other workspace. |
| The name is blank, 201 characters long or ends in a line break | 422 VALIDATION_FAILED on name. | The naming rules. |
| A member tries to create a workspace | 403 FORBIDDEN. Nothing is created. | Only organization owners and admins create workspaces. |
| A member with the workspace role member tries to rename it | 403 FORBIDDEN. The name stays. | Renaming needs the effective role owner or admin. |
| A member with the workspace role admin renames the workspace | It works. | The effective workspace role is what counts for renaming. |
| That same workspace admin tries to delete the workspace | 403 FORBIDDEN. | Deleting needs the organization role owner or admin. |
| A plain member of the organization tries to delete a workspace they are not a member of | 404 NOT_FOUND, as for an unknown ID. | Someone who cannot open a workspace cannot tell it exists. |
| An organization admin who belongs to no workspace creates or renames one | It works. | Admins reach every workspace through their role. |
| An admin creates a workspace and is later made a plain member | They can no longer open it, unless someone added them to it. | Creating a workspace does not make its creator a workspace member. |
| Someone outside the organization reads, renames or deletes a workspace | 404 NOT_FOUND, as for an unknown ID. | Outsiders cannot tell the workspace exists. |
| The workspace ID is not a valid UUID | 404 NOT_FOUND. | A malformed ID names nothing. |
| Someone who is not in the organization is added to a workspace | 404 NOT_FOUND. | Only organization members can be workspace members. Invite them first. |
| A workspace member tries to add or remove workspace members | 403 FORBIDDEN. | That needs the effective role owner or admin. |
| A workspace admin tries to give the workspace role owner | 403 FORBIDDEN. | Only an effective workspace owner gives owner. |
| A workspace admin tries to remove a workspace owner's membership | 403 FORBIDDEN. | Only an effective workspace owner removes one. |
| Someone is added with the role they already have | 200. Nothing changes. | There is nothing to do. |
| The membership of someone with no workspace membership is removed, for example an organization admin's | 404 NOT_FOUND. | There is no workspace membership to remove. Their access comes from the organization role. |
| An organization admin's workspace membership is removed | They still open the workspace, now with source organization. | Admins reach every workspace. |
| A member is removed from a workspace they have open | Their next action is refused. They read "You no longer have access to {workspace}" and are taken to another workspace. | Access ends at once. |
| A member is removed from a workspace an API key of theirs names | The key no longer reaches that workspace (404 NOT_FOUND). It still reaches its other workspaces. | A credential reaches a workspace only while its member does. |
| A plain member is added to a workspace and removed again | They gain access, then lose it, both at once. | Workspace membership is the only thing giving a plain member access. |
| The delete request names the workspace in the wrong case ("docs" for "Docs") | 422 VALIDATION_FAILED on confirmName. Nothing is deleted. | The name must be repeated exactly. |
| The person deleting has not verified their email | 403 EMAIL_NOT_VERIFIED. Nothing is deleted. | Deleting needs a verified email. |
| The only workspace is deleted | 409 CONFLICT, reason LAST_WORKSPACE. | An organization keeps at least one live workspace. |
| An organization has one live and one deleted workspace, and the live one is deleted | 409 CONFLICT, reason LAST_WORKSPACE. | A deleted workspace is not "another workspace". |
| A deleted workspace is deleted again | 404 NOT_FOUND. | It is already gone from view. |
| Two admins each delete one of the organization's two workspaces at the same moment | One succeeds. The other gets 409 CONFLICT, reason LAST_WORKSPACE. | The two requests are handled one after the other. |
| An admin deletes the last-but-one workspace while another creates a new one | Both succeed, in some order, and at least one live workspace remains. | Creating and deleting are handled one after the other. |
| A member has the workspace open when it is deleted | They read "You no longer have access to {workspace}" and are taken to another workspace, or to "No workspace yet". | Nobody can work in a deleted workspace. |
| A file of the deleted workspace was public | Its public link answers "not found". After a restore the same link works again. | Nothing in a deleted workspace is public, and links are kept for a restore. |
| A signed download link was made just before the deletion | It stops working. After a restore it works again until it expires. | Links into a deleted workspace are refused. |
| An API key named only the deleted workspace | The key is still valid but reaches no workspace. After a restore it reaches the workspace again. | Credential scopes are kept for a restore. |
| Someone creates an API key naming a deleted workspace | 422 VALIDATION_FAILED on workspaceIDs. | A deleted workspace cannot be named. |
| A pending invitation named the deleted workspace and one other | The invitation lists only the other workspace. Resending it sends an email that names only the other. After a restore it lists both again. | Invitations keep their workspaces for a restore but do not show deleted ones. |
| That invitation is accepted while the workspace is deleted | The person joins the organization and the other workspace only. Restoring the workspace later does not add them. | Accepting adds live workspaces only, and the invitation is used up. |
| A new invitation names a deleted workspace | 422 VALIDATION_FAILED on workspaceIDs. | A deleted workspace cannot be named. |
| An export runs while a workspace is deleted | The archive leaves out that workspace and everything in it. | Exports hold live workspaces only. |
| A new workspace takes the deleted workspace's name, and the deleted one is restored | 409 CONFLICT, reason NAME_TAKEN. The deleted one stays in the deleted list. | A restore never leaves two workspaces with one name. |
| The live workspace is then renamed and the restore repeated | The workspace is restored with its original name. | The name is free again. |
| A member or an outsider asks for the deleted list | The member gets 403 FORBIDDEN, the outsider 404 NOT_FOUND. | Only organization owners and admins see deleted workspaces. |
| A member tries to restore a workspace, also one they are a member of | 404 NOT_FOUND, as for an unknown ID. | Only organization owners and admins see deleted workspaces and restore them. |
| A live workspace is "restored" | 404 NOT_FOUND. | Only a deleted workspace can be restored. |
| A workspace is restored twice, for example from two browsers | The second attempt gets 404 NOT_FOUND. The app reports no failure: it reloads the lists, and the workspace is under "Workspaces". | It is already live. |
| A restore is attempted after the deadline | 404 NOT_FOUND. The workspace is no longer in the deleted list. | The window is over, even if removal has not happened yet. |
| A restore arrives at the very moment of removal | Either the restore wins and the workspace is back, or removal wins and the restore gets 404 NOT_FOUND. Never half of each. | The two are handled one after the other. |
| A workspace is deleted, restored and deleted again | The second deletion starts a new 30 days. | The deadline is set at each deletion. |
| The organization is deleted while one of its workspaces is deleted | The workspace's own deadline keeps running. Restoring the organization does not restore it. | A workspace deletion and an organization deletion are separate. |
| A workspace of a deleted organization is restored | 404 NOT_FOUND. | Restore the organization first. |
| An upload was being checked when its workspace was deleted | It finishes in the background. After a restore the file is there. | A restorable workspace keeps its content complete. |
| Your remembered workspace is deleted | The app forgets it and opens another workspace. | The remembered workspace is only a preference. |
| A file was already in the workspace's trash when the workspace was deleted | Its own trash period keeps running. When that period ends the file is deleted for good, also while the workspace is deleted. A later restore of the workspace comes back without it. | Deleting a workspace does not pause the trash. See Trash and restore. |
Errors
| Code | Status | When | What to do |
|---|---|---|---|
UNAUTHENTICATED | 401 | Not signed in, or an invalid credential. | Sign in or use a valid credential. |
FORBIDDEN | 403 | Your role does not allow the action: see "Who can do what". | Ask an organization owner or admin. |
FORBIDDEN, reason SESSION_REQUIRED | 403 | A credential calls a session-only operation. | A person does this in a browser. |
FORBIDDEN, reason INSUFFICIENT_SCOPE | 403 | A credential without workspace:read lists a workspace's members. | Use a credential with that scope. |
EMAIL_NOT_VERIFIED | 403 | Deleting a workspace with an unverified email. | Open the verification link, or ask for a new one. |
NOT_FOUND | 404 | The workspace is unknown, deleted, in a deleted organization or out of your reach; the person is not an organization member; there is no workspace membership to remove; a restore of something not deleted or past its deadline, or by someone who is not an owner or admin of the organization. | Check the ID with GET /v1/workspaces. |
CONFLICT, reason NAME_TAKEN | 409 | Creating or renaming to a name another live workspace has. Message: "a workspace with this name already exists". | Choose another name. |
CONFLICT, reason LAST_WORKSPACE | 409 | Deleting the organization's only live workspace. | Create another workspace first, or delete the organization. |
CONFLICT, reason NAME_TAKEN | 409 | Restoring while a live workspace has the name. Message: "A workspace has this name now; rename it, then restore this one". | Rename the live workspace, then restore. |
VALIDATION_FAILED | 422 | name breaks the naming rules; confirmName is not the workspace's name; role is not a role; the body is not the expected JSON. details.field names the field where there is one. | Correct the field. |
RATE_LIMITED | 429 | A credential passed its request limit. | Wait for Retry-After seconds. |
See Errors for the shape of every error.
Limits
| What | Value |
|---|---|
| Workspace name | 1 to 200 characters after trimming, no control characters, unique in the organization ignoring case |
| Live workspaces per organization | At least 1, no upper limit |
| Members per workspace | No limit |
| Restore window of a deleted workspace | 30 days from the deletion |
| Page size of a workspace member list | 1 to 100, default 50 |
| Workspaces one API key or connected app can name | 1 to 20 |
Questions and answers
What should be a workspace? One brand, client or business whose files and people you want to keep apart from the others.
Do members see every workspace? No. Members see only the workspaces they were added to. Owners and admins see all of them.
How do I give someone access to a workspace? If they are in the organization, open the workspace's settings page and add them under "Members". If they are not, invite them to the organization and tick the workspaces in the invitation.
I created a workspace and my colleague cannot see it. Why? A new workspace has no members. Add your colleague to it, unless they are an owner or admin.
Can two workspaces have the same name? Not in one organization, and case does not matter. Different organizations can reuse a name.
Can I move a workspace to another organization? No.
Can I move files between workspaces? See Folders, moving and finding.
Who can rename a workspace? Organization owners and admins, and members who are owner or admin of that workspace.
Who can delete a workspace? Organization owners and admins with a verified email. Being owner of just that workspace is not enough.
Where are a workspace's settings? Under "File spaces" in the settings navigation: choose the workspace, and its own navigation offers "General" and "Statuses, fields and tags". Settings > Organization > Workspaces links each workspace's settings page too.
Why is there no "Delete workspace" on my workspace's settings page? You are not an owner or admin of the organization, or it is the organization's only workspace.
Why is "Delete workspace" disabled? Your email address is not verified. Verify it first.
What happens to the files when I delete a workspace? They become unreachable at once but are kept for 30 days. If the workspace is restored in that time, everything is back. After 30 days they are deleted for good.
Do public links keep working after a workspace is deleted? No. They stop at once. After a restore the same links work again.
Can I restore a deleted workspace? Yes, for 30 days, as an owner or admin of the organization: Settings > Organization > Workspaces, under "Deleted workspaces".
Do the members come back with a restore? Yes. Every member, role, file, invitation and credential that named the workspace is as it was.
The restore says another workspace has the name. What now? Rename the live workspace that took the name, then restore again.
Can I delete a workspace for good right away? No. Removal happens after the 30 days.
Can I delete the last workspace? No. Create another workspace first, or delete the whole organization.
Can I leave a single workspace? Not by yourself as a plain member. An owner or admin of the workspace removes you, or you leave the organization.
I had the workspace open and it vanished. What happened? It was deleted, or you were removed from it. The app tells you "You no longer have access to {workspace}" and opens another one.
Does my API key still work after its workspace is deleted? The key works for its other workspaces. It cannot reach the deleted one until that is restored.
Can an agent create, rename or delete workspaces? No. A credential lists the workspaces it reaches and reads their members.
Is anyone emailed when a workspace is created, renamed, deleted or restored? No.