Security

Whether your are a developer getting started with the Box API or a Box Admin tasked with authorizing applications, it is critical you understand the security mechanisms in place to protect content stored in Box.

The Box API follows the same security principals 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 Access Token. 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 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 downscoping a token.

Access Tokens are only valid for 60 minutes, but can be revoked earlier if needed. Once an Access Token expires, when using an OAuth 2.0 application, a Refresh Token can be exchanged for another Access Token. Refresh tokens are valid for 60 days or one use. Alternatively, when using a server authentication application, the request Access Token endpoint must be called for a new Access Token. For security reasons we do not allow long-lived access tokens.

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 preform 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 reference documentation for a given endpoint if it is required.

Some Admin-restricted endpoints include:

• Creating, deleting, or getting information about users
• Creating, deleting, or modifying groups
• Viewing user or enterprise events

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 security classifications
• Interacting with legal hold policies and assignments
• Interacting with retention policies and assignments

Application Access

Application access is only configured in the Developer Console for applications leveraging Server Authentication with JWT) or Client Credentials Grant. This setting determines the types of users that can be used with the application. The two options are app access only or app + enterprise access.

Upon authorizing one of these applications in the Box Admin Console, a Service Account (AutomationUserxxxx@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 user’s of the application called App Users. If an application only needs to interact with the Service Account and App Users, app only access must be selected. If an application needs to interact with managed users 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 authorized 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.

Custom applications fall into two categories: published and unpublished. Published applications are found in the Box App Center. Box Admins decide whether published and unpublished application are enabled by default and therefore can be used without approval. The status of these settings determines what actions are necessary to successfully authorize an application for use.

Regardless of the settings above, in order for an application leveraging JWT or Client Credentials Grant to be used by an enterprise, an Admin must explicitly authorize 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 enable any application leveraging OAuth 2.0 as the authentication method.

Additionally, if this setting is turned on, Server Authenticated apps will also require enablement.