Learn how JWT authentication works
Prerequisites
To set up a Platform App using JWT, you need to ensure you have access to the Developer Console from your Box enterprise account. Alternatively, you may sign up for a developer account.App creation steps
Create a Server Authentication app
- Log into Box and go to the Developer Console.
- Click New App.
- Select Server as the app type.
- Click Create.
Select JWT as the authentication method
How you set the method to JWT depends on your enterprise’s Switch server app auth type (CCG or JWT) setting:- When switching is enabled, the app is created using Client Credentials Grant (the default). Open the Configuration tab and change the authentication method to JWT.
- When switching is disabled, the Create a New App dialog shows a Select Method step with Client Credentials Grant preselected. Choose JWT there, because the method is fixed once the app is created.
When switching is enabled, you can change between JWT and
at any time from the Configuration tab. See
for details on credential handling and downtime considerations.
Public and private key pair
Once your app is configured to use JWT, a key pair can be generated via the Configuration tab in the Developer Console. Alternatively, you can generate your own and supply Box with the public key. Regardless of the method you select, your Box account needs to have 2FA enabled for security purposes.Generate a keypair (Recommended)
If you would like to use a Box generated keypair, navigate to the Developer Console where you can generate a configuration file. This file includes a public/private keypair and a number of other application details that are necessary for authentication. To generate this file, navigate to the Configuration tab of the Developer Console and scroll down to the Add and Manage Public Keys section.
For security reasons, Box does not store your private key. If you lose your
private key, you need to reset the entire keypair.
Manually add keypair
Alternatively, you may generate your own keypair and upload the public key to the Developer Console. To create a keypair using OpenSSL, open a terminal window and run the following commands.For Windows SystemsWindows users can install and use the Cygwin package to run OpenSSL.
App Authorization
Server authentication applications must be authorized before use. The authorization process depends on your account type. Free developer accounts: Your app is automatically authorized when you create it. If authorization did not complete, the Configuration tab displays a prompt to authorize the app. Enterprise accounts: After you create the app, the Configuration tab prompts you to submit the app for admin approval. Enterprise admins and co-admins: The Configuration tab lets you authorize the app directly after creation.Learn more about the authorization process
Basic configuration
Application Access
An application’s access level determines which users and content your app may access. By default, an application can only successfully interact with the content of its and any . To access existing Managed Users of an enterprise and groups that were not created by the app itself, navigate to the App Access Level setting accessible on the Configuration tab of the Developer console and set to App + Enterprise Access. Otherwise, access to such Managed Users and groups is blocked.
Application Scopes
An application’s scopes determine which endpoints and resources an application can successfully call. See the for detailed information on each option.
CORS Domains
If your application makes API calls from front-end browser code in Javascript, the domain that these calls are made from needs to be added to an allow-list due to Cross Origin Resource Sharing, also known as CORS. If all requests are made from server-side code, you may skip this section. To add the full URI(s) to the allow-list, navigate to the CORS Domain section at the bottom of the Configuration tab in the Developer console.