- Apps that people sign in to are User apps, which always use OAuth 2.0.
- Apps that run on their own are Server apps, which use either Client Credentials Grant (CCG) or JWT.
Authentication methods at a glance
The methods differ in how your app proves who it is, and in the content the resulting token can reach.
A Server app has to be authorized before it can call the API. An OAuth 2.0 app needs a Box Admin or Co-Admin to enable it only when your enterprise leaves unpublished apps inactive by default. covers both cases.
Set up JWT authentication
Learn about Box access tokens
OAuth 2.0
OAuth 2.0 is an open standard that lets people grant an application access to their data in another application. If you’ve ever signed in to a website with Google or Facebook, you’ve used it. Box follows the same flow: your app sends the user to Box, the user logs in and approves the request, and Box returns an authorization code that your app exchanges for an access token. Because the token belongs to the person who signed in, your app reaches exactly the content that user owns or collaborates on, and the content it creates lives in that user’s own account. Choose OAuth 2.0 when your users already have Box accounts and you want them to sign in to Box themselves.Learn about OAuth 2.0 authentication
Client Credentials Grant
Client Credentials Grant (CCG) verifies your application’s identity with a client ID and client secret, then returns an access token directly. No one logs in, so it suits code that runs unattended. CCG is preselected when you create a Server app. Each token request names the subject it authenticates as: the application’s , or a specific user when the app is configured to allow it. Choose CCG for a backend service, an automation, or an integration whose end users have no Box accounts of their own or sign in through your identity system. Each of those users can get an isolated App User with its own folder tree.Learn about Client Credentials Grant
JWT
Server authentication with JSON Web Tokens (JWT) has your app sign a short-lived assertion with a private key rather than send a secret on its own, then exchange that assertion for an access token. Box holds only the matching public key, so the private key never leaves your infrastructure. JWT gives you the same Service Account model as CCG, including isolated App Users. The assertion doesn’t replace your client secret, which the token request still carries, so JWT adds a second factor to the exchange rather than swapping one credential for another.Learn about JWT authentication
Choosing between CCG and JWT
Both methods reach the same Service Account, the same App Users, and the same content, so the choice comes down to how your app proves who it is and how much credential handling you want to own. Choose JWT when your security review calls for keypair-based verification, or when you want the private key to stay in your infrastructure: Box stores only your public key, so a leaked client secret alone isn’t enough to get a token. The cost is key management, including generating the keypair, protecting the private key and its passphrase, and uploading a new public key whenever you rotate. Choose CCG otherwise. It needs no keys and no assertion signing, which makes it the simpler option and the one Box recommends for most Server apps. Whether you can change the method after the app exists depends on an enterprise setting, and switching revokes the credentials tied to the previous method.Switch an existing app between CCG and JWT
Credentials for each method
Each method needs a different set of values, and all of them come from the Configuration tab of your app in the .Your Box account needs multi-factor authentication (MFA) enabled to view a client secret or generate a keypair.
Where credential files live
JWT is the only method where Box hands you a file. When you select Generate a Public/Private Keypair in the Developer Console, Box downloads aconfig.json that holds both the keypair and the application details needed to authenticate. Store that file securely outside source control and load it at runtime, or load the same values from environment variables or a secrets manager. The guide shows what the file contains and how to load it.
If you generate your own keypair and upload only the public key, there’s no config.json to download. Store the private key wherever your application can read it at startup, keep the passphrase separate from the key, and read the remaining values from the Configuration tab. OAuth 2.0 and CCG apps have no file at all, so keep their client ID and client secret in environment variables or a secrets manager.
Read the authentication best practices
Access token
Every method ends in the same place: Box returns an access token, and your app sends it in theAuthorization header of each API call. The token is valid for 60 minutes, and the response reports the exact lifetime in seconds as expires_in.
How each method requests a token
Every method requests the token from the same endpoint,https://api.box.com/oauth2/token, and sends a different grant_type with the parameters that accompany it. OAuth 2.0 reaches this request last, after the user has already signed in at Box and consented.
code that Box returns after the user consents, and JWT needs an assertion you sign with your private key. The guide walks through building that assertion, and the handle both steps for you.
What comes back
What arrives alongside the token differs by method, and it decides how your app keeps working once the token expires.
A refresh token lasts 60 days and works only once, so an OAuth 2.0 app stores the newest refresh token for each user and sends that user through authorization again if 60 days pass without a refresh. CCG and JWT apps skip this bookkeeping, because they request a fresh token whenever they need one.
Who the token represents
An access token always maps to one Box user, and that user determines which content your app can reach and where new content lives. What the token can do with that content is narrower still: it’s the overlap between the user’s own access and the you enabled for the application, so a call can fail even when the user can see the file.
Every Box account has its own folder tree, and the root of that tree is always folder ID
0. The same upload call therefore lands in a different place depending on which token you send it with: an OAuth 2.0 token puts the file in the signed-in user’s account, while a Service Account token puts it somewhere only the application can see until you share it. Nothing crosses between trees on its own, so if your app has to work with content that already exists, give the account access first.
Service Accounts
A Service Account is a programmatic user that represents your application inside the Box enterprise. Box generates it automatically once your JWT or CCG app is , so you never create it yourself. It has no login credentials and acts only through the API, which makes it a good fit for backend integrations. You find its@boxdevedition.com email address in the App Details tab of your app, next to a link that opens the account in the Content Manager.
A Service Account starts with an empty folder tree, so it can’t see your existing files until you give it access. Invite it as a collaborator using its email address, or call the with its user ID. covers its storage quota, its scopes, and how an Admin browses its content.
Server apps aren’t limited to the Service Account. A CCG app can request a , and a JWT app can send the header or request a . In each case the Managed User or App User keeps their own folder tree.