Setup with Client Credentials Grant

Prerequisites

To set up a Platform App using server-side authentication, 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. Your Box account also needs multi-factor authentication (MFA) enabled, because Box requires it before it shows the application’s client secret on the Configuration tab.

App creation steps

Create a Server Authentication app

Log into Box and go to the Developer Console.
Select New App.
Select Server as the app type.
Leave Client Credentials Grant selected under Select Method.
Select Create.

Client Credentials Grant (CCG) is preselected for new Server Authentication apps, so selecting Create without changing the method produces a CCG app. Your enterprise’s Switch server app auth type (CCG or JWT) setting only affects whether you can change the method later. It is enabled by default for free developer accounts and disabled by default for enterprises, so in an enterprise treat the method as fixed once the app is created.

When switching is enabled, you can change to at any time from the Configuration tab. See for details.

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 also access existing Managed Users of an enterprise, navigate to the App Access Level setting on the Configuration tab of the Developer console and set to App + Enterprise Access.

To authenticate as a Managed User or Admin, enable Generate User Access Tokens in the Additional Configuration section of the Configuration tab.

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.

Get an access token

Post your client ID and client secret to the with a grant_type of client_credentials, and name the subject you want to authenticate as.

curl -X POST https://api.box.com/oauth2/token \
    -d "grant_type=client_credentials" \
    -d "client_id=[CLIENT_ID]" \
    -d "client_secret=[CLIENT_SECRET]" \
    -d "box_subject_type=enterprise" \
    -d "box_subject_id=[ENTERPRISE_ID]"

curl -X POST https://api.box.com/oauth2/token \
    -d "grant_type=client_credentials" \
    -d "client_id=[CLIENT_ID]" \
    -d "client_secret=[CLIENT_SECRET]" \
    -d "box_subject_type=user" \
    -d "box_subject_id=[USER_ID]"

The same user request authenticates an App User, a Managed User, or an Admin. Which of them you can request a token for depends on the app’s configuration: an App User needs Generate User Access Tokens, and a Managed User or an Admin needs App + Enterprise Access as well.

Common errors

Grant credentials are invalid

During authentication, you can encounter the following error:

Grant credentials are invalid [400 Bad Request] invalid_grant - Grant credentials are invalid

This error indicates one of the following:

The client ID and client secret passed are incorrect or are not for the same application.
The box_subject_id can’t be used based on the selected application access.

A CCG app with App Access Only can send in the box_subject_type of enterprise to authenticate as its Service Account, but it can’t authenticate as a Managed User or an Admin.

Your application isn’t configured to generate user access tokens. Enable Generate User Access Tokens in the Advanced Features section of the Configuration tab.

Once you make changes to the app settings, don’t forget to the application in the Admin Console.

Your application has not been authorized in the Box Admin Console.

Using SDKs and Client Credentials Grant

To learn more about Client Credentials Grant for each SDK head over to:

Getting started

Applications & integrations

Identity & access

Using the API

Troubleshooting

Content

Collaboration

Metadata & search

Events & webhooks

Users

Intelligent workflow

E-signatures

Security & compliance

Setup with Client Credentials Grant

Prerequisites

App creation steps

Create a Server Authentication app

App authorization

Learn more about the authorization process

Basic configuration

Application access

Application scopes

CORS domains

Get an access token

Common errors

Grant credentials are invalid

Using SDKs and Client Credentials Grant

​Prerequisites

​App creation steps

​Create a Server Authentication app

​App authorization

Learn more about the authorization process

​Basic configuration

​Application access

​Application scopes

​CORS domains

​Get an access token

​Common errors

​Grant credentials are invalid

​Using SDKs and Client Credentials Grant

Prerequisites

App creation steps

Create a Server Authentication app

App authorization

Basic configuration

Application access

Application scopes

CORS domains

Get an access token

Common errors

Grant credentials are invalid

Using SDKs and Client Credentials Grant