Skip to content
File Service

Manage access for the resources

Note: The content on this page primarily applies to the v2 API. However, the access model and roles are the same in v1 and v2 of the API.

Access Model

An additive, inheritance-based access model is used for File Service. Access is managed through the ACL field on a resource. ACLs are available on all of the primary File Service entities: spaces, folders, files, and objects.

In this model, ACLs are inherited by default from parent resources to their children. This means that setting an ACL on a folder implicitly applies that ACL to all its children (folders, files, and objects) recursively. If a folder and its children have their own ACLs, these ACLs are merged before they are evaluated.

When a resource is moved or the resource hierarchy changes, the permissions of the resources in that hierarchy are updated to reflect the permissions inherited from the new parent.

Updating ACLs

Permissions can be updated through updates on the metadata (eg. PATCH to /files). These updates require submitting the full array in the request. Learn more about managing ACL permissions. (For managing permissions in the v1 API see here.)

Supported Roles

  • Space Manager
  • Content Manager
  • Content Contributor
  • Content Viewer
  • Support File Admin
  • Limited Viewer

Each role has a set of permissions associated with it. Space roles apply to space-level permissions. Content roles apply to files and folders.

Space Roles

Space Operation Space Manager
Get x
Update x
Delete x
Restore x
Manage Access x

Content Roles

Folder/File/Object Operation Content Manager Content Contributor Content Viewer Limited Viewer
Create x x
Get x x x x
Update x x
Rename x x
Copy x x
Move x
Delete x
Restore x
Manage Access x
> **Note:** The `Limited Viewer` role is more restrictive than the `Content Viewer` role. While both roles allow viewing spaces, folders and files, `Limited Viewer` can access only a subset of fields compared to `Content Viewer`.

Support File Admin Role

The Support File Admin role is a system role that allows support files to be system managed. This role can bypass the checkout on a main file, but only to manage the support file links. This role can only manage links, no other operations are available to this role. This role is assigned at the space level and will apply to all files in the space, and is limited to applications.

Inheritance Control

  • The inherits field allows controlling whether permissions should be inherited from parent resources
  • When inherits is set to false on a resource, only permissions explicitly set on the resource and space will apply

Permission Fields

  • permissionsLocal: Permissions explicitly assigned to the resource.
  • permissionsInherited: Permissions inherited from parent resources.
  • permissionsInheritedFoldersOnly: Permissions inherited from parent resources, excluding space and local permissions
  • permissionsEvaluated: The effective permissions after applying inheritance rules.
  • capabilities: The specific actions the current user can perform on the resource.

Permission Assignment

  • The actor who creates a space is automatically assigned the spaceManager role
  • Additional roles can be assigned via the permissionsLocal field
  • Permissions use a direct mapping between actors and roles.

Permission Evaluation Examples

Example 1: All folders inherit permissions

When the inherits field is set to true on all folders in a hierarchy, and an actor has different roles at different levels:

LevelFolderRole On ResourceInherits
1Root_FolderContentManagerTrue
2Level1_FolderContentContributorTrue
3ParentFolderContentViewerTrue
4TestFolder-True

The evaluated permission for the actor accessing the TestFolder would be ContentManager inherited from Root_Folder, because the most permissive role is applied.

Example 2: Inheritance blocked at Level 2

When the inherits field is set to false on one of the folders:

LevelFolderRole On ResourceInherits
1Root_FolderContentManagerTrue
2Level1_FolderContentContributorFalse
3ParentFolderContentViewerTrue
4TestFolder-True

The evaluated permission for the actor accessing the TestFolder would be ContentContributor, inherited from Level1_Folder. This is because the inherits field is set to false on the Level1_Folder, which blocks any permissions from above that level.

For more information on the permissions, please refer to the permission model overview section in the API Spec.