Building Custom Applications with Box Platform
We’ve listened to feedback from developers building on our platform and introduced a new way of building on Box: App Auth and App Users.
- App Auth: Box’s new authentication feature allows your application to authenticate directly to Box using a JSON Web Token (JWT) grant and RSA keypair. An overview of the JWT (JSON Web Token) technology can be reviewed here. This authentication replaces the first leg of the standard 3-legged OAuth process in which a user grants an application permission to access the user’s Box account, removing the friction of multiple logins and services for your users.
- App Users: a new type of full-featured enterprise Box account that belong to your application, not a Box end-user. Unlike typical Box accounts, these accounts do not have an associated login and can only be accessed through the Content API by the controlling application and associated Box user id. This new user model allows your application to take advantage of groups, permissions, collaborations, comments, tasks, and the many other features offered by the Box platform.
In the standard Box integration, applications integrate directly with pre-existing Box accounts, granting access to user-specific content; however, these accounts remain owned by the end-user and their associated enterprise. With App Auth and App Users, developers have access to all of the functionality of Box’s Content API while also owning the user authentication, user accounts, and content associated with their application.
Getting a Developer Account
To build custom applications using App Auth and App Users, you will first need to create a developer account and an application using the Content API. Once you have created a developer account, create your first application and choose the Content API. You can get started by following the instructions to get an API key.
Enable App Auth and App Users for your Application
Once you have an account, App Auth requires certain scopes to be enabled for your API key. You can enable them through the developer console by following the steps outlined below.
Configure App Auth with a Public Key
After following the steps below, you will need to add a Public Key for your application following the steps outlined here.
Because App Auth and App Users is designed for server-to-server authentication, we require that you enable two-factor authentication to use these features.
Two-Factor Authentication Not Required with SSO
If you are using an SSO-enabled account, two-factor authentication is not required.
To enable 2FA, log in to your account at developers.box.com and select My Apps. Click the gear and select Account Settings.
Select the Security menu and choose Login verification and follow the instructions to enable two-factor authentication.
When you have entered your phone number and submitted the correct verification code, you will see the following message:
Configuring Your API Key
To activate App Auth and App Users for your app, you will need to configure the User Type in the Application Configuration. Go to developers.box.com, then choose My Apps, and finally Edit Application.
Under OAuth2 Paramters, select App Users under the User Type setting. This will select the required OAuth2 scopes for your application.
For a full description of scopes, please refer to the Scopes section of our OAuth2 documentation.
Once you have selected the proper scopes, scroll to the bottom of the page and click Save Application.
Enterprise Access Required
In order to begin creating App Users in an enterprise, access to your application must be granted in the Enterprise Admin console. If you are building on a developer enterprise, follow the instructions below.
1) Once you are logged into Box, click on Admin Console at the top of the screen.
2) Access your Enterprise Settings by clicking on the Gear in the top right corner and selecting Enterprise Settings.
3) In the Enterprise Settings Menu, click on Apps.
4) Scroll down to Custom Applications, and click on Authorize New App.
5) Enter the API key for the app you would like to enable, and select an access level. This determines which users the app has control over. It is important to select the access level for an application carefully. This option determines which sets of users an application may access and modify within your enterprise.
At this point in time, App Auth can only be used with App Users of your application.
Only App Users of this App (Recommended)
Limits access to only the App Users created and managed by this application.
6) Click Okay. The app is now enabled within your Developer enterprise.
7) Once you have enabled the app for your enterprise, you will need to add a Public Key to begin using App Auth and App Users. Follow the instructions here.