Box Platform Basics: Authentication Methods 101

Published in

Box Developer Blog

7 min readAug 29, 2023

TL;DR —Discover Box Platform’s authentication methods (OAuth 2.0, JWT, CCG, & App Token) that apps use to access its services, explained through a real world analogies and examples.

Have you ever wondered how applications gain access to the Box API? You’re not alone! In fact, I’ve been right there with you — especially at the beginning of my own Box journey. Here at Box Platform, we field numerous questions about Box’s authentication methods. In this blog post, I will explore and demystify the different options.

Authentication — a house with many locks

When I think about API authentication, I imagine a house secured by multiple locks. Each entry point possesses its unique method for unlocking the door and granting access. Nevertheless, all these locks are operated by a common device, which corresponds to an API token in technical terms. Using Box Platform is no different, and we offer four ways to get a token.

OAuth 2.0
JSON Web Tokens or JWT for short
Client Credentials Grant or CCG for short
App Auth

Let’s investigate each of them separately.

OAuth 2.0 — the treasure chest

The most common authentication method customers use is OAuth 2.0. This option requires users of the application to login using their Box account, meaning they will know they are using Box. I commonly refer to this as client side or front end authentication.

Imagine you have a treasure chest with your favorite jewels inside, and you want a appraiser to take a look at some of them. But you don’t want to give them the key to the entire treasure chest. Instead, you give them a magic badge. This badge lets them open the chest and analyze only the jewels you want to sell. When the appraiser shows the magic badge to the treasure chest, it makes sure it’s real and that it’s for the right jewels. Also, the magic badge doesn’t work forever — it only works for a little while, like for the duration of an appointment.

This is just like OAuth 2.0 and Box. You own or have access to certain content in Box, and you would like to share that content with other applications. You provide them a way to access that content by logging into your Box account. Box verifies you are who you say you are and have access to what the application is trying to access. Box keeps them from doing things they aren’t supposed to do — like see all your enterprise’s users, and their access is time bound.

Real world example

An email marketing tool that wants to access a user’s files stored in Box in order to attach them as campaign assets. Instead of a user uploading them individually, they use a OAuth 2.0 web app integration that allows the application access to the user’s content in Box.

When to use

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

JSON web tokens (JWT) — the digital passport

The second most common authentication method customer’s use is JWT. This option happens behind the scenes in an application, meaning a user wouldn’t know that Box is being used. I commonly refer to this as server side authentication V1.

Picture yourself traveling internationally — you need a passport that proves your identity wherever you go. Similarly, JSON Web Tokens serve as digital passports in API communication scenarios by securely transmitting claims about users’ identities.

In Box, an application setup for JWT authentication has a JSON config file that can be used directly by our SDKs. This config file is the passport I referenced earlier.

Real World Example

A large bank uses a custom loan application portal to streamline their financing division. As part of the process, customers upload various documents that need stored somewhere securely. The customers don’t have or don’t need Box accounts. Instead, the portal uses a custom Box application using JWT authentication. When a customer creates a login on the portal, an app user is created in Box to store content. An app user is one that doesn’t have front end Box access.

When to use

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

Client credentials grant (CCG)— the vip access badge

The newest authentication method Box has released is CCG. This option also happens behind the scenes in an application, meaning a user wouldn’t know that Box is being used. I commonly refer to this as server side authentication V2, since it is newer than JWT.

Consider attending an exclusive event where only authorized attendees have entry privileges thanks to special badges issued specifically for them — this is similar to how client credentials grant works! It enables server-to-server communication without involving end-users’ interaction. It also has a lower barrier to entry than the “passport” required for JWT, since you only need the client id and client secret of the custom Box application.

Real World Example

An analytics software needs to retrieve and analyze usage data from various Box accounts for reporting purposes. The platform uses a client ID and secret from a custom Box application using client credentials grant. The software queries Box’s API to gather usage data, such as the number of files, storage usage, and collaboration activities. It processes and analyzes the collected data to generate usage reports and insights for each Box account.

When to use

work with 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

App token auth — the secret handshake

Server-side app token auth is an authentication method where the application only has access to read and write data to its own account. This is used by Box View applications. By using this authentication method there is no need to authorize a user as the application is automatically authenticated as the application’s Service Account.

Imagine being part of a secret society where members identify each other through unique handshakes — this is akin to using app tokens! These tokens are specific to an application and grant access based on predefined permissions.

Real World Examples

Since this method is only valid for Box View use cases, below are some common ones to think about.

Convert and display PDF resumes in a recruiter application
Convert and display course materials, including documents, videos, and PDFs in a student portal
Convert and display HD video in a media room
Convert and display sales collateral, including documents, videos, PDFs, and 3D models in a field sales enablement application

When to use

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

Bringing it all together

Box provides developers with four different authentication methods when creating applications: OAuth 2.0, JSON web tokens (JWT), Client Credentials Grant (CCG), and App Token Auth. Each option provides its own set of customizations and specified uses. Due to the complexities of setting up this piece of an application, it is very easy to get confused or lost. Hopefully, this blog post helps you understand the differences and gets your current or future applications up and running more quickly.

Happy Coding!