# 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](../files/overview.md).

## 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](members-and-roles.md#workspace-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 FORBIDDEN` with
  `details.reason` `SESSION_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](../files/statuses.md) and
  [Fields and tags](../files/fields-and-tags.md).
- 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](../files/library-and-suggestions.md).

### 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](organizations.md#creating).
- 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`,
  reason `NAME_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`, reason `NAME_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](../agents/credentials.md).
- 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](../reference/permissions.md).
- 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](../files/sharing.md).

### Workspace membership

- A workspace membership gives one organization member a role in one
  workspace: `owner`, `admin` or `member`.
- 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](invitations.md).
- 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`: `workspace` for a workspace membership,
  `organization` for 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-last-workspace-rule).
- The answer is `202` with the workspace's ID, name, `deletedAt` and
  `purgeAfter`. `purgeAfter` is 30 days after `deletedAt`.

The checks happen in this order. The first that fails decides the answer:

1. Not signed in: `401 UNAUTHENTICATED`.
2. The workspace is unknown or already deleted, its organization is deleted,
   or you cannot open the workspace: `404 NOT_FOUND`.
3. You can open the workspace but are a plain member of the organization:
   `403 FORBIDDEN`.
4. Your email is not verified: `403 EMAIL_NOT_VERIFIED`.
5. `confirmName` is not the workspace's name: `422 VALIDATION_FAILED` on
   `confirmName`.
6. It is the organization's only live workspace: `409 CONFLICT` with
   `details.reason` `LAST_WORKSPACE`.
7. 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](delete-and-restore.md).

### 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 `200` with the workspace and your effective role in it.
- No email is sent.

The checks happen in this order:

1. Not signed in: `401 UNAUTHENTICATED`.
2. 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.
3. A live workspace has its name, ignoring case: `409 CONFLICT` with
   `details.reason` `NAME_TAKEN`.
4. 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`, reason `NAME_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`, reason
  `LAST_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](../files/statuses.md)).
  - "Custom fields", its custom fields and their options
    (`.../files/fields`; see
    [Fields and tags](../files/fields-and-tags.md#custom-fields)).
  - "Tags", its tags (`.../files/tags`; see
    [Managing tags](../files/fields-and-tags.md#managing-tags)).

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}/library` or
  `/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:

1. **General.** The workspace's name. See
   [Renaming a workspace](#renaming-a-workspace).
2. **Members.** Everyone who can open the workspace. See
   [Workspace members in the app](#workspace-members-in-the-app).
3. **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](#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

1. Choose "New workspace" on the Workspaces page or in the workspace
   switcher.
2. The dialog "New workspace" has the field "Workspace name" and the button
   "Create workspace".
3. 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

1. Open the workspace's settings page.
2. In the section "General", change "Workspace name" and choose "Save".
   "Save" is disabled until the name differs from the current one.
3. 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:
  1. "Choose a member" lists the organization's members who do not reach the
     workspace yet.
  2. The role choice lists the roles you may give: "Member" and "Admin", and
     "Owner" if you are an owner there. It starts on "Member".
  3. "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

1. 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."
2. 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."
3. Type the workspace's name into "Confirm workspace name". The hint reads
   `Type "{name}" to confirm.`
4. The dialog's "Delete workspace" stays disabled until the name matches
   exactly.
5. 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:

```sh
curl -s "$TALEWRIGHT/v1/workspaces" \
  -H "Authorization: Bearer $TALEWRIGHT_API_KEY"
```

```json
{
  "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 `id` as `workspaceID` to the workspace tools.
- Pass `organizationID` to the `library_` 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/workspaces` lists the
  workspaces the caller reaches, and reading the organization lists its
  workspaces. `/v1/workspaces/{workspaceID}` takes `PATCH` and `DELETE`
  only.

### 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](members-and-roles.md#listing-members).

### 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](../files/trash.md). |

## 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](../reference/errors.md) 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](../files/organizing.md).

**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.

## Related pages

- [Organizations](organizations.md)
- [Members and roles](members-and-roles.md)
- [Invitations](invitations.md)
- [Export](export.md)
- [Deleting and restoring](delete-and-restore.md)
- [Files & Assets overview](../files/overview.md)
- [Trash and restore](../files/trash.md)
- [Sharing and public links](../files/sharing.md)
- [Credentials and scopes](../agents/credentials.md)
- [Roles and permissions](../reference/permissions.md)
- [Limits](../reference/limits.md) and [Errors](../reference/errors.md)

