User permissions and scopes
It is important to understand that even if an application has the right scopes to perform an action, the user associated with the Access Token making the call needs to have permission to perform the action as well and vice versa. For example, if your application is set up to read files, the authenticated user does need to have permission to read the file you are trying to access. To learn more about how scopes, token permissions, and user permissions work together, see our .Scopes & OAuth 2 authorization
When sending a user through a client-side OAuth 2 flow to authorize your application it is possible to append a set of scopes to the authorization URL to further restrict the user’s access token. For example, if you application has theroot_readonly and root_readwrite
scopes enabled, it is possible to restrict a user’s access token to
root_readonly by specifying this scope when redirecting the user.
Self-service scopes
These scopes are available through the Developer Console when configuring an application. Navigate to the Application Scopes section of the Configuration tab and select one or more of the following scope.Read all files and folders
Gives an application the ability to read all the files/folders for the
authenticated user.
Although this gives an application the permission to read files and folders, the
user making the API call does need to have access to the items being accessed.
In the case of a application accessing a
items, the Service Account’s Token will need to either use the
as-user
or create a to directly authenticate as
the user who has access to the content.
Read and write all files and folders
Gives an application write access for the authenticated user. This allows the
application to upload files or new file versions, download content, create new
folders, update or delete collaborations, create comments or tasks, and more.
Although this gives an application read/write access to items, the
user making the API call needs to have access to the content.
Manage users
The manage users scope in the Developer Console maps to two OAuth scopes.
Gives an application permission to manage . It
allows the app to change the user’s primary login, reset their password, and
change roles for managed users.
Although this allows an application manage users, for client-side applications,
the Access Token used must be associated with an Admin or Co-Admin with the
correct permissions.Additionally, for JWT applications, the application must be configured with
App Access + Enterprise Access .
Gives an application permission to manage , which means this
scope only applies to server-side authenticated (JWT) applications.
Manage groups
Gives an application permission to manage an enterprise’s groups. It
allows the app to create, update, and delete groups, as well as manage group
membership.
Although this allows an application to manage groups, for client-side applications,
the Access Token used must be associated with an Admin or Co-Admin with the
correct permissions.For JWT applications, groups the app creates itself can be managed with
App Access Only. To manage groups that were not created by the app itself,
the application must be configured with App Access + Enterprise Access
.
Manage webhooks
Gives an application permission to create webhooks for a user.
Please review webhook . Most
notably, there is a limit of 1000 webhooks per application, per user.
Manage enterprise properties
Gives an application permission to view the enterprise event stream, as well as
view and edit the enterprise’s attributes and reports. It also allows the
application to edit and delete device pins.
Although this allows an application to enterprise properties, for client-side
applications, the Access Token used must must be associated with an
Admin Co-Admin with the correct permissions.
Manage retention policies
Gives an application permission to view and create retention policies
with Box Governance. This requires the enterprise to have purchased
Box Governance.
Manage signature requests
Gives an application permission to get, create, cancel, and resend sign
requests.
This scope requires the application to also have read/write scopes, which are
automatically selected when enabled. In addition, an enterprise must have Sign
enabled.
Manage Box AI API
Gives an application permission to send requests to
Box AI API.
Manage Box Relay
Gives an application permission to get workflows and start flows of type
WORKFLOW_MANUAL_START
This scope requires the application to also have read/write scopes.
Available on request
There are some additional scopes that are only available upon request. To do so, please submit a ticket to our support team. They will review these requests on an individual basis and only provide approval if the use case requires the scope.It is not possible to request extra scopes if your account is a free trial
account. Before filing a support request for activation of the following
scopes, log in to your paid enterprise account or
upgrade your free developer account to an enterprise account tier.
Manage Legal Holds
Gives an application permission to view and create retention policies
with Box Governance. This requires the enterprise to have purchased Box
Governance.
This scope depends on the
enterprise_content scope to function properly.
This scope can be requested by opening a ticket via our support channels.Suppress email notifications
Allows some types of to be suppressed when API
calls are made.
Global Content Manager (GCM)
Allows Admins, Co-Admins, and to retrieve any content
they do not own or are not collaborators on within their enterprise, based on
their enterprise settings.
This scope is required to manage the retention policies and legal holds.
Side effectsEnabling this scope on an application changes the behavior of some API calls,
and most notably, makes it impossible to write content without explicitly
authenticating as a user using the
as-user header. Additionally, enabling this
scope disables accessing content that is owned by users in another enterprise.For this reason, this scope will not be provisioned unless absolutely necessary.Scopes for downscoping
In some cases an Access Token needs to be to a more strict permission level, especially when a token needs to be exposed to a client-side, public environment like a browser. The primary example for this is when using Box UI Elements, which require an Access Token in the user’s browser. The following is a list of additional scopes that can be used with the endpoint to downscope an existing access token.
The standard OAuth scopes are also supported when downscoping.