> For the complete documentation index, see [llms.txt](https://docs.maiagent.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.maiagent.ai/maiagent-user-guide/en/work/file-library/shared-spaces.md).

# Shared Spaces

Share files across departments using shared spaces, grant access by role, preview who will gain access before creating a space, and automatically update visibility when roles change.

Shared spaces are suitable for files that multiple departments need, but the entire organization does not, such as launch materials used by sales and marketing. Access to shared spaces is granted by **role**: members can see a space when their roles qualify. When their roles change, the spaces they can see update automatically, without configuring access for each person.

## Use Case <a href="#use-case" id="use-case"></a>

The sales and product departments need to prepare materials together for a new product launch. The marketing manager creates a shared space named “A1 Launch | Sales and Marketing” in the file library and selects <mark style="color:blue;">Sales Department</mark> and <mark style="color:blue;">Product Department</mark> as authorized roles. The bottom of the dialog immediately lists the members who will gain access. Later, when a colleague transfers to the sales department, the manager does not need to configure anything else: the colleague sees this space when they log in to the file library.

***

## Create a Shared Space <a href="#create-shared-space" id="create-shared-space"></a>

### 1. Open the Creation Dialog <a href="#open-create" id="open-create"></a>

In the space tree on the left of the file library, click <mark style="color:blue;">＋</mark> (<mark style="color:blue;">Create shared space</mark>) next to <mark style="color:blue;">Shared spaces</mark>.

### 2. Enter a Name and Authorized Roles <a href="#name-and-roles" id="name-and-roles"></a>

Enter a <mark style="color:blue;">Space name</mark> and select the custom roles to grant access to under <mark style="color:blue;">Authorized roles</mark> (default roles cannot be selected). You can also leave the roles unselected and add them later. Only the creator and organization owner can see a space with no authorized roles. If the organization has no custom roles, the list displays “No custom roles yet. Create a custom role first.” Anyone with role management permission can click <mark style="color:blue;">Go to role settings</mark>. The <mark style="color:blue;">Members who will gain access</mark> section below lists members in these roles in real time. It also indicates if any member lacks the “Can be invited to shared spaces” permission.

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-7ff36a40432bb0ae490d9ce7e648dd3f41b0d44f%2Ffile-library-shared-space.png?alt=media" alt="Create shared space dialog with Sales Department and Product Department selected as authorized roles and a preview below of members who will gain access"><figcaption><p>Preview which members will gain access before creating the space</p></figcaption></figure>

### 3. Confirm Creation <a href="#confirm-create" id="confirm-create"></a>

Click <mark style="color:blue;">Confirm</mark> to add the shared space to the space tree. As with other spaces, only file workspaces can be created at the top level of a shared space. Workspaces also support <mark style="color:blue;">Start conversation from here</mark>, workspace instructions, and version history.

***

## Who Can See a Shared Space <a href="#who-can-access" id="who-can-access"></a>

Members can see a shared space when they meet both conditions:

1. Their role is included in the space's <mark style="color:blue;">Authorized roles</mark>
2. Their role has the <mark style="color:blue;">Can be invited to shared spaces</mark> permission

The creator can always see the space. Organization owners do not need permission to be invited, but their role must still be among the authorized roles. They can also see the space if all authorized roles have been deleted. Shared space access can only be granted to roles, not to individual people. To grant access to a specific member, add them to the appropriate role.

{% hint style="info" %}
Creating or deleting shared spaces, or changing a space's name or authorized roles, requires the <mark style="color:blue;">Create shared spaces</mark> permission. For permission settings, see [Role and Permission Management](https://docs.maiagent.ai/maiagent-user-guide/en/org/roles/role-permission.md#permission-structure-overview).
{% endhint %}

***

## Edit and Delete <a href="#edit-and-delete" id="edit-and-delete"></a>

* **Edit**: Open <mark style="color:blue;">Edit shared space</mark> for the space to change its name or authorized roles. You can also clear all authorized roles. Changes are recorded in the space's version history.
* **Delete**: A space cannot be deleted while it still contains content. Empty it first.
* **When there are no authorized roles** (because the selection was cleared or all authorized roles were deleted): Only the creator and organization owner retain access. Add authorized roles again when needed.

***

## Related Pages <a href="#related" id="related"></a>

* [File Library](https://docs.maiagent.ai/maiagent-user-guide/en/work/file-library.md)
* [Role and Permission Management](https://docs.maiagent.ai/maiagent-user-guide/en/org/roles/role-permission.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.maiagent.ai/maiagent-user-guide/en/work/file-library/shared-spaces.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
