Authentication Methods

Box Platform Learn Box Platform Authentication Methods

Authentication Methods

Box offers a variety of authentication methods for application development, each tailored to different use cases and application types. Regardless of the authentication method used, underlying principles still apply. If a user does not have access to content on the front end of the main Box web app, they will not be able to access the content using the API, unless they are impersonating another user. Some API endpoints require admin level privileges - like events.

The following authorization methods are available to each Box application type.

Box Application Type	Supports OAuth 2.0?	JWT?	Client Credentials?	App Token?
Custom App	Yes	Yes	Yes	No
Limited Access App	No	Yes	No	Yes
Custom Skill	No	No	No	No

OAuth 2.0 is a client-side authentication method, widely used for its simplicity in authorizing users to Box API. It's an open standard that allows users to grant applications access to their data in other applications. Similar to how logging in to a website with Twitter, Facebook, or Google works, Box's client-side authentication involves redirecting a user from an app to the Box web app, where they log in and grant the app access to their data. For example, We use this auth type for users logging into our community forum.

When to use OAuth 2.0?

Client-side authentication is the ideal authentication method for apps that:

Work with users who have existing Box accounts
Use Box for identity management, so users know they are using Box
Store data within each user account vs within an application's Service Account

You can find a great Python OAuth 2.0 tutorial on GitHub.

JSON Web Tokens (JWT) is the most common server-side authentication method for the Box API. JWT, an open standard, enables robust server-to-server authentication. This method, exclusive to Custom Apps, does not involve end-user interaction. It allows an app, if granted appropriate privileges, to act on behalf of any user in an enterprise, thus facilitating powerful and seamless integrations. Upon approval by an administrator, a JWT application will get assigned a service account to make API calls as by default.

When to use JWT?

Server-side authentication with JWT is the ideal authentication method for apps that:

Work with users without Box accounts
Use their own identity system
Do not want users to know they are using Box
Store data within the application's Service Account and not a user's account
Want to manage public and private key pairs

You can find a great Node JWT tutorial on Medium.

The Client Credentials Grant approach is used for server authentication, verifying an application's identity using a client ID and secret. It's a secure way of identifying an app when obtaining an Access Token. This method is particularly useful for scenarios requiring server-to-server interactions without user involvement. Depending on the application's configuration, it can authenticate as either the application's Service Account or as a Managed User. Upon approval by an administrator, a CCG application will get assigned a service account to make API calls as by default.

When to use CCG?

Server-side authentication with JWT is the ideal authentication method for apps that:

Work with users without Box accounts
Use their own identity system
Do not want users to know they are using Box
Store data within the application's Service Account and not a user's account
Do not want to manage public and private key pairs

You can find a great Python CCG tutorial on Medium.

App Token Authis another server-side authentication option, utilizing fixed, long-lived Access Tokens that are restricted to the application's Service Account. This method is ideal for applications leveraging Box View and is designed for scenarios where the app only needs access to read and write data to its own account. By using App Token Auth, there's no need for end-user authorization, as the application automatically authenticates as the Service Account associated with it. It also is restricted to a subset of API endpoints.

When to use App Token Auth?

Server-side authentication with App Tokens is the ideal authentication method for apps that:

Work in an environment that either has no user model, or has users without Box accounts
Use their own identity management system
Do not want users to know they are using Box
Store data within the application's Service Account and not a user's account

Box Skills are a unique application type used for custom processing of files uploaded to Box. It uses third-party Machine Learning services to extract information from files and apply it as metadata. Authentication for Custom Skills is streamlined with pre-authorized API credentials provided with each Skill Event, though this limits the API access. Custom Skills don't require a specific authentication type selection, focusing on simplicity and direct integration with Box's capabilities.

When to use Box Skills?

Webhook based authentication with Box Skills is the ideal authentication method for apps that:

Work in third party machine learning environments
Potentially want users to know they are using Box
Achieve an end goal in tandem with other processes
Only want to process files that trigger the Box Skill

You can find a great Box Skills tutorial on Medium.

When an application is created in the Developer Console, the user must configure application scopes. Similar to how users have permissions to access files and folders within Box, applications have their own set of permissions to perform certain actions on behalf of a Box user or a Box enterprise. The name for a set of permissions for an application is a "scope". In short, an application's scopes determine which endpoints an application can successfully call and are reflected in the access provided by Access Tokens of the application.

It is important to understand that even if an application has the right scopes to perform an action, the user associated with the Access Token making the call needs to have permission to perform the action as well and vice versa.

For example, if your application is set up to read files, the authenticated user does need to have permission to read the file you are trying to access.

To learn more about how scopes, token permissions, and user permissions work together, see our security guide.

Next step

Authentication Methods

Authentication Methods

OAuth 2.0

When to use OAuth 2.0?

JSON Web Token (JWT)

When to use JWT?

Client Credentials Grant (CCG)

When to use CCG?

App Token Auth

When to use App Token Auth?

Box Skills

When to use Box Skills?

Scopes

User permissions and scopes