Box API: Understanding Security
Whether it is your first time using the Box API or you are a Box Admin tasked with authorizing custom applications, it is critical you understand the security mechanisms in place to protect content stored in Box. By the end of this post, I hope you walk away with a better understanding of how access is restricted when interacting with the Box API. If you’re already familiar with the Box Web App, always keep in mind that the API will follow the same security principals and restrictions.
Tokens
At the core of every Box API call is an access token. Because a username and password cannot be used to make calls, the Box servers need a way of validating user identity. Access tokens represent the authenticated user and determines 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. That can be further restricted by downscoping a token.
Access tokens are only valid for 60 minutes, but can be revoked at any time. Once that time is up, a refresh token, valid for 60 days or one use, can be passed in exchange for another access token. For security reasons, we do not allow for long-lived access tokens.
Tip: Receiving an error, especially a 404, and don’t know why? A great place to start is checking to see what user is associated with your access token using the get current user endpoint.
Application Scopes
When an application is created in the Developer Console, the user must configure application scopes. Scopes determine which of our 150+ endpoints an application can successfully call and are reflected in the access provided by access tokens of the application. This means that granting the write scope does not give a user automatic access to all content in a Box enterprise, they’ll just be able to preform actions like renaming folders they have access to or creating new ones.
As an example, let’s say you create an application with just the manage users and manage groups scope enabled. If you try to make an API call to get information about a folder, even if you have access to it, you will receive a 403 error. However, if you make an API call to create a user, the call will be successful as long as your access token is associated with an Admin who can create users.
Restricted Endpoints
There are some API endpoints that only Admins or Co-Admins with the proper granted permissions can successfully use. As a general rule of thumb, if only an Admin/Co-Admin can perform an action via the Box Admin Console, an access token associated with one of these users must be used to make the API for the same action. This is called out in our API reference documentation for the endpoint if 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 token if an enterprise has purchased add-on products like Box Governance or Box Shield.
Some of these endpoints include:
- Interacting with security classifications
- Interacting with legal holds and legal hold policies
- Interacting with retention policies
Application Access
Application access is only configured in the Developer Console for applications leveraging Server Authentication (with JWT). This determines the types of users can interact with the app. The two options are app access only or app + enterprise access.
Upon authorizing a JWT application in the Box Admin Console, a Service Account (AutomationUser_xxxx_@boxdevedition.com) for the application is automatically generated. This account is an Admin-like user that can only be accessed via the API. This user can then be used to create user’s of the application called App Users. Simply put, if an application needs to interact with managed users and their existing Box content, app + enterprise access must be selected. Remember, granting app + enterprise access does not mean the app gets access to all the content in the Box enterprise.
As an example, let’s say we have a JWT application with the read/write scopes, app only access, and is properly authorized in the Admin console. Then, a managed user obtains an access token for the application and makes an API call to a folder they own. What do you think will happen? Will the call be successful or not and why?
If you said the call will fail, you are correct. The 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 and authorization all check out, the application access only allows for the service account and app users to interact with the application.
Enterprise Settings & Authorization
There are a few enterprise settings to be aware of when it comes to the Box API.
In order for JWT application to be used by an enterprise, an Admin must explicitly authorize and enable it in the Box Admin console. This is done by navigating to Apps > Custom Apps and clicking the + button. The authorization is a snapshot in time meaning if a developer revisits the Developer Console and changes the configuration, the Admin must re-authorize the application for the changes to take effect.
Custom applications fall into two categories: published and unpublished. Published applications are found in the Box App Gallery. Box Admins decide whether published and unpublished application are enabled by default and therefore can be used without approval. These settings are accessible in the Admin Console under Apps > Custom Apps tab and clicking the ⚙️ button.
If an Admin enables the setting to disable published application by default, they must use the Admin console to navigate to:
Apps > Box Apps & Integrations tab > Individual App Controls
Search for the application you would like to enable. If you see a button that says clear filters, make sure you click it or you may have trouble finding the application. Click the dropdown next to the application and set to Available.
If an Admin enables the setting to disable unpublished applications by default, the steps they must take to enable an application differ depending on the application’s authentication method.
- OAuth 2.0: An Admin must add the application’s API key to the allow-list in order for calls to be successful
- Server Authentication (with JWT): An Admin must authorize the application and add the API key to the allow-list, shown in the screenshot above, in order for calls to be successful.
Please note that if an Admin does not enable the setting to disable unpublished applications by default, they will still need to authorize all JWT applications. This only eliminates the need to also add the JWT applications to the allow-list.
Overview
- Access Tokens determine what content an app can successfully call
- Application Scopes determine which API endpoints an app can successfully call
- Restricted Endpoints can only be used by Admin or Co-Admin access tokens
- Application Access (JWT only) determines what types of users can interact with the app.
- Enterprise settings determine if applications are disabled by default.
- Authorization is required by a Box Admin in order for JWT apps to interact with a Box enterprise.
Did you find this post helpful? Please give it a like or let us know in the comments. We’d love to hear your feedback!
