Authentication Models

Box offers two types of authentication. You must choose one or the other in order to use the Box REST API. The correct choice depends on the type of application you're building.

OAuth 2

OAuth 2 requires a user to log in to Box and grant your application permission to access files and folders. The OAuth 2 standard defines a three-legged authentication process; Box conforms to this process.

The Box implementation of OAuth 2 is designed to be used with managed users and external users. An external user is an account created by a Box user for that person's own use.

A managed user is an account that was created by an administrator for use by another person. A common example of a managed user is an account created for you by a company you work for or an organization you belong to. The managed user account is yours, but the administrator controls certain policies and permissions that apply to your account.

OAuth 2 with JSON Web Tokens

OAuth 2 with JSON Web Tokens enables an application to connect directly to Box and obtain authorization to access files and folders without requiring users to log in. Using OAuth 2 with JSON Web Tokens an application can provide Box features without users even being aware that Box exists.

Instead of requiring the user to log in to Box, the application generates JSON Web Token (JWT) verified by an RSA keypair. If this authentication succeeds then the application obtains an access token that grants authorization to operate on Box files and folders.

This machine-to-machine authentication replaces the first leg of the three-legged authentication process defined by OAuth 2, and enables users of your application to work with Box content without seeing Box login requests.

OAuth 2 with JSON Web Tokens is designed to be used with Box Platform. You can use OAuth 2 with JWT with both Service Accounts and App Users.

Choosing an Authentication Type

Build a Box Integration
Build on Box Platform

Description

Allow users to access, edit, and save their Box content within your third-party app, such as an e-signature or project management service.

Build a standalone app with Box's content services, such as managing and rendering files and enabling end-user collaboration.

Authentication Mechanism

OAuth 2.0 (3-legged)

OAuth 2.0 with JSON Web Tokens

Users

Managed Users

OAuth 2 Scopes

Scope
Description

Read and write all files and folders

Scope name: root_readwrite

Allows the application to upload, view, download file versions, and update the current file version.

Allows the application to create, edit, and delete collaborations, tags, tasks, comments, @mentions, task assignments, notifications, and collections.

Allows the application to view the enterprise profile.

Manage an enterprise

Scope name: manage_enterprise

Full set of scopes available for performing enterprise management, which includes permissions to view, create, edit, and delete users, content, collaborations, groups, reports, and admin settings.

Manage an enterprise's managed users

Scope name: manage_managed_users

Subset of the Manage an enterprise scope

Allows the application to add, view, edit, delete, activate, and disable standard Box users.

Allows the application to change the primary login, reset password, and change role for managed users, as well as manage enterprise content.

Manage an enterprise's groups

Scope name: manage_groups

Subset of the Manage an enterprise scope

Allows the application view, create, edit, and delete groups and group memberships.

Manage an enterprise's properties

Scope name: manage_enterprise_properties

Subset of the Manage an enterprise scope

Allows the application to view and edit enterprise attributes and reports; edit and delete device pinners.

Manage an enterprise's retention policies

Scope name: manage_data_retention

Allows the application to view and create content retention policies with Box Governance. Learn more here.

Create and manage app users

Scope name: manage_app_users

Allows the application to provision and manage its own App Users using the App Auth feature. Learn more here.

Manage Webhooks

Scope name: manage_webhook

Enables you to create webhooks programmatically through the API. See more here

Global Content Manager
Scope name: Admin or co-admin can make calls for any content in their enterprise

To enable this you will need to file a support ticket to get the Box team to enable it for your application. Scope approval will be approved by necessity and merit. This scope may be required for certain applications relying on retention and legal holds.

Enabling this scope on an application disallows making calls to externally owned content with that application.

Admin can make calls on behalf of Users

To enable this you will need to file a support ticket to get the Box team to enable it for your application. Scope approval will be approved by necessity and merit.

Can suppress email notifications from API calls

To enable this you will need to file a support ticket to get the Box team to enable it for your application. Scope approval will be approved by necessity and merit.

Changing Scopes After App Authorization

If you change your application's scopes after the Admin has authorized your application in their Box enterprise, these new scopes will not be reflected in that Box enterprise until the Admin reauthorizes your application in the Admin console.

Advanced Features

Warning:

These should only be used for server-side development with JSON Web Tokens.

Scope
Description

Perform Actions as Users
Scope name: Admin can make calls on behalf of Users

Allows your application to make API calls on behalf of users using the As-User header.

Generate User Access Tokens

Allows your application to generate OAuth 2.0 access tokens for users using a JWT grant instead of the user providing credentials.

Questions
If you have any questions, please visit our developer forum.


What's Next

Account Types

Authentication Models