Skip to main content
Whether you are a developer getting started with the Box API or a Box Admin tasked with applications, it is critical you understand the security mechanisms in place to protect content stored in Box. The Box API follows the same security principles and restrictions as the Box web app. This means that you will not be able to bypass content permissions, the waterfall folder structure, or Admin-only requirements by leveraging the Box API.

​
Access Tokens

At the core of every Box API call is an . Because a username and password cannot be used, the Box servers need a way of validating user identity. The full capability of an Access Token encompasses user permissions, token permissions, and application settings.
Access Token Components
Access Tokens represent the authenticated user and determine what content a user can successfully call. Similar to using the Box Web App, you will only be able to successfully interact with content the user, associated with the Access Token, either owns or is a collaborator on. This can be further restricted by a token. are only valid for 60 minutes, but can be earlier if needed. Once an Access Token expires, when using an OAuth 2.0 application, a can be for another Access Token. Refresh tokens are valid for 60 days or one use. Alternatively, when using a server authentication application, the must be called for a new Access Token. For security reasons we do not allow long-lived access tokens.
Unsure why you are receiving a 404 error? A great place to start is checking to see what user is associated with your Access Token by using the get current user endpoint.

​
Scopes

Scopes
are configured in the Developer Console upon application creation. They determine which of the 150+ endpoints Access Tokens of an application can successfully call. Because scopes work in conjunction with user permissions, granting the write scope does not automatically provide a user with API access to all content in a Box enterprise. Instead, it means that the authenticated user can receive successful API responses when making write calls to content they have access to. For example, take an application with only the manage users and manage groups scopes enabled. If an Access Token of this application tried to make an API call to get information about a folder, even if the associated user owned it, it would receive a 403 error. This is because the read scope is required to perform this action. Access Tokens of this application could only receive successful responses on API calls related to users and groups.

​
Restricted endpoints

There are some API endpoints that only Admins or Co-Admins, granted the appropriate permissions, can successfully use. As a general rule of thumb, if only an Admin or Co-Admin can perform an action via the Box Admin Console, an Access Token associated with one of these users is required to complete an API call for the same action. This is called out in our API documentation for a given endpoint if it is required. Some Admin-restricted endpoints include:
  • Creating, deleting, or getting information about
  • Creating, deleting, or modifying
  • Viewing user or enterprise
Other endpoints can only be used by an Admin user’s Access Token if the enterprise has purchased add-on products such as Box Governance or Box Shield. Some of these endpoints include:
  • Interacting with
  • Interacting with and
  • Interacting with and

​
Application Access

Application Access Settings
Application access is only configured in the Developer Console for applications leveraging Server Authentication with or . This setting determines the that can be used with the application. The two options are app access only or app + enterprise access. Upon one of these applications in the Box Admin Console, a (AutomationUser_xxxx_@boxdevedition.com) representing the application is automatically generated. This account is an Admin-like user that can only be accessed via the API and can then be used to create users of the application called . If an application only needs to interact with the Service Account and App Users, or with content they own or are collaborated on, app only access must be selected. If an application needs to interact with and their existing Box content, app + enterprise access must be selected. As an example, take a JWT application that has the read/write scopes, app only access, and is properly in the Admin console. If a managed user obtains an Access Token and makes an API call to a folder they own, that call would receive a 400 error with the message “Cannot obtain token based on the enterprise configuration for your app”. Even though the user has access to the content, the correct scopes are enabled and the app is authorized, the selected application access only allows the application to interact with the Service Account and App Users.

​
Enterprise settings and authorization

There are a few enterprise settings to be aware of when it comes to the Box API.
Global Integration Settings
Platform applications fall into two categories: published and unpublished. Published applications are found in the Box Integrations. Box Admins decide whether published and unpublished applications are enabled by default and therefore can be used without approval. The status of these settings determines what actions are necessary to successfully an application for use.
Admin Console Apps Tab
Regardless of the settings above, in order for an application leveraging or to be used by an enterprise, an Admin must explicitly it via the Box Admin console. The authorization is a snapshot in time. This means that if a developer revisits the Developer Console and changes the configuration, the Admin must re-authorize the application in order for generated Access Tokens to reflect the changes. If the setting Disable unpublished apps by default is turned on, an Admin must also explicitly any application leveraging as the authentication method. Additionally, if this setting is turned on, Server Authenticated apps will also require enablement.
Last modified on September 7, 2026