Skip to main content
Before uploading files to Box and previewing them using Box View, a Box Platform App must be created and configured for server authentication.

Create a Platform App

​
Choose an authentication method

Box View works with any server-side authentication method. Choose the one that fits your needs.
The authentication method cannot be changed after creation. If you need a different method, create a new application.
MethodBest forKey trait
Client Credentials Grant (CCG)Most Box View use casesSimple setup; uses client ID and a secret
JWTEnvironments that require public/private key securityKey-pair based; no shared secret over the wire
Both methods authenticate as the application’s Service Account, which owns all uploaded content — no end-user login is required.
Migrating from a Limited Access App: CCG and JWT Platform Apps support every endpoint that Limited Access Apps (App Token authentication) support plus 150 more. The file upload, download, delete, and preview workflows are identical. See the Select Auth Method guide for a full comparison.

​
Configure application settings

To configure your application, in the Developer Console, navigate to the Configuration tab of your application, and then set the following options:
  1. For Application Access, select App Access Only. This restricts the application to its own Service Account content, which is the standard configuration for Box View.
  2. For Application Scopes, enable at least the following options:
    • Read all files and folders stored in Box (root_readonly)
    • Read and write all files and folders stored in Box (root_readwrite)
  3. If your application makes API calls from front-end browser code (for example, using Box UI Elements), add your domains to the CORS allow-list at the bottom of the Configuration tab.
  4. Copy your credentials from the Configuration tab:
    • For CCG, copy the Client ID and the Client Secret. To view the secret, multi-factor authentication is required.
    • For JWT, download the JSON config file after generating a public/private key pair.

​
Authorize your application

Server-authenticated Platform Apps require admin authorization before they can make API calls.
  1. In the Developer Console, navigate to the Authorization tab.
  2. Click Review and Submit. Your enterprise’s Box Admin will receive an email to approve the application in the Admin Console. For more information, see the Platform App Approval guide.
If you try to make API calls before the app is authorized, you receive the following error: “error”: “unauthorized_client”

​
Obtain an access token

The process for obtaining an access token depends on the authentication method of your application.

​
Client Credentials Grant (CCG) authenticated Platform Apps

Request an access token by sending your client ID and secret to the token endpoint. The token authenticates as the application’s Service Account.
cURL
curl -X POST https://api.box.com/oauth2/token \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "grant_type=client_credentials" \
  -d "box_subject_type=enterprise" \
  -d "box_subject_id=YOUR_ENTERPRISE_ID"
The response contains an access token valid for approximately 60 minutes:
Response
{
  "access_token": "c3FIOG9vSGV4VHo4QzAy...",
  "expires_in": 4169,
  "restricted_to": [],
  "token_type": "bearer"
}
Your application should request a new token before the current one expires. All Box SDKs handle this automatically: 
from box_sdk_gen import BoxClient, BoxCCGAuth, CCGConfig

auth = BoxCCGAuth(
    config=CCGConfig(
        client_id="YOUR_CLIENT_ID",
        client_secret="YOUR_CLIENT_SECRET",
        enterprise_id="YOUR_ENTERPRISE_ID",
    )
)
client = BoxClient(auth=auth)

​
JWT authenticated Platform Apps

If your application uses JWT authentication, use the JSON config file downloaded during setup: 
from box_sdk_gen import BoxClient, BoxJWTAuth, JWTConfig

jwt_config = JWTConfig.from_config_file("/path/to/config.json")
auth = BoxJWTAuth(config=jwt_config)
client = BoxClient(auth=auth)
For more information about JWT setup, see the JWT authentication guide.

​
Downscope tokens for client-side use

If you need to pass an access token to the browser (for example, to run Box Content Preview or other Box UI Elements), always downscope the token first. Downscoping exchanges a full-privilege token for a new token with restricted permissions and an optional file-level scope.
cURL
curl -X POST https://api.box.com/oauth2/token \
  -d "subject_token=YOUR_ACCESS_TOKEN" \
  -d "subject_token_type=urn:ietf:params:oauth:token-type:access_token" \
  -d "grant_type=urn:ietf:params:oauth:grant-type:token-exchange" \
  -d "scope=item_preview" \
  -d "resource=https://api.box.com/2.0/files/FILE_ID"
The downscoped token is short-lived and limited to the specified scope and file. Use it in client-side code instead of the original access token. The following table lists common downscope scopes for Box View:
ScopeDescription
item_previewPreview a file
item_downloadDownload a file
base_previewBasic preview (Box Content Preview element)
annotation_editEdit and delete annotations
annotation_view_allView all annotations
For the full list of downscope scopes, see the scopes guide.

​
Security best practices

Follow these guidelines to ensure your Platform Apps are secure:
  • Never expose your client secret or full access token in client-side code. Always downscope before sending tokens to the browser.
  • Store credentials securely. Use environment variables or a secrets manager for your client ID, client secret, and enterprise ID.
  • Keep Application Access set to App Access Only unless you specifically need enterprise-wide content access.
  • Add only necessary CORS domains. Restrict the allow-list to the domains that actually make browser-side API calls.

​
Legacy Limited Access Apps

Limited Access Apps use App Token authentication, which provides a pair of fixed, long-lived tokens (Primary and Secondary) that are manually generated in the Developer Console. This approach is being replaced by CCG and JWT authentication, which offer programmatic token management, automatic refresh, and access to the full Box API. If you have an existing Limited Access App, follow these steps to migrate your content to a new CCG or JWT authentication app:
  1. Create a new Platform App using CCG or JWT following the steps above.
  2. Reupload your content to the new app’s Service Account, or use collaborations to share existing content.
  3. Replace hard-coded App Tokens with programmatic CCG or JWT token acquisition.
  4. Update any downscoped token calls. The POST /oauth2/token token-exchange flow is identical; only the subject_token value changes.
The file upload, preview, and embed workflows are identical regardless of the authentication method. No changes are needed to your iframe embeds or Box UI Element code beyond swapping the access token.