> ## Documentation Index
> Fetch the complete documentation index at: https://developer.box.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Collaborations
> Grant users and groups role-based access to files and folders, manage pending invitations, and apply collaboration domain restrictions.
export const Link = ({href, children, className, ...props}) => {
const localizedHref = localizeLink(href);
return
{children}
;
};
Collaborations define access permissions for users and groups on files and folders, similar to access control lists. A collaboration object grants a user or group access to a file or folder with permissions defined by a specific role.
Use the guides in this section when you need to invite collaborators, share with groups, handle pending invitations, or manage enterprise collaboration domain restrictions through the API.
## How collaborations work
When you create a collaboration, you specify three things:
1. **Item** — The file or folder being shared (`type` of `file` or `folder`, plus its `id`).
2. **Accessible by** — Who receives access: a `user` (by ID or email login) or a `group` (by ID).
3. **Role** — The permission level granted to that user or group.
Box applies the same permission model through the API as in the Box web app. You cannot bypass content permissions or the [waterfall folder structure][waterfall] by using the API. Access tokens only succeed against content the authenticated user owns or is a collaborator on — see the security overview.
Collaborations are distinct from shared links. Shared links provide URL-based access to an item. Collaborations grant role-based access to a specific user or group and appear in the item's collaborator list.
## Roles
The collaboration roles are `editor`, `viewer`, `previewer`, `uploader`, `previewer uploader`, `viewer uploader`, `co-owner`, and `owner`.
For a full description of each role, see the [collaborator permission levels][support documentation] support article.
## Collaboration status
A collaboration invitation can be in one of these states:
| Status | Meaning |
| ---------- | ----------------------------------- |
| `pending` | The invitee has not accepted yet |
| `accepted` | The collaborator has access |
| `rejected` | The invitee declined the invitation |
You can list pending invitations for the current user with `GET /collaborations?status=pending`.
## Users and groups
* **Users** — Share with a managed or external user by user ID or email. See Share content with a user.
* **Groups** — Share once with a Box group so every group member inherits the same role. See Sharing with groups.
You can also build integrations that create Box groups from external systems and collaborate those groups on folders — for example, the Slack group collaborations tutorial.
## Enterprise domain restrictions
Admins can limit who can be invited as collaborators by allowing only specific email domains. Applications with the right permissions can add, list, and delete those allowed domains programmatically. See Allowed collaboration domains.
## Quick example
Invite a user as an editor on a folder:
```bash theme={null}
curl -X POST https://api.box.com/2.0/collaborations \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"item": { "type": "folder", "id": "FOLDER_ID" },
"accessible_by": { "type": "user", "login": "user@example.com" },
"role": "editor"
}'
```
## Guides in this section
Create a collaboration on a file or folder for a user by ID or email.
Grant the same role to every member of a Box group in one collaboration.
List invitations the current user has not accepted yet.
Manage enterprise allow-lists that restrict which email domains can collaborate.
Sync Slack channels to Box groups and share files with the channel in one command.
[support documentation]: https://support.box.com/hc/en-us/articles/360044196413-Understanding-Collaborator-Permission-Levels
[waterfall]: https://support.box.com/hc/en-us/articles/360043697254-Understanding-Folder-Permissions