Box Developer Documentation

Client Credentials Grant

Guides Authentication Client Credentials Grant
Edit this page

Client Credentials Grant

Follow the steps below if you would like to leverage server authentication and verify your application's identity using a client ID and client secret.

Prerequisites

  • A Custom Application using Server Authentication (with Client Credentials Grant) authentication in the Box Developer Console
  • 2FA enabled on your Box account for viewing and copying the application's client secret from the configuration tab
  • The application is authorized in the Box Admin Console

Your client secret is confidential and needs to be protected. Because this is how we securely identify an application's identity when obtaining an Access Token, you do not want to freely distribute a client secret. This includes via email, public forums and code repositories, distributed native applications, or client-side code. If you would like to add more security mechanisms, we recommend using our standard JWT application type.

How to use

When making your API call to obtain an Access Token, your request body needs to contain your client ID and client Secret. Set the grant_type to client_credentials.

If you would like to authenticate as the application's Service Account:

  • set box_subject_type to enterprise
  • set box_subject_id to the enterprise ID
cURL
curl -i -X POST "https://api.box.com/oauth2/token" \
     -H "content-type: application/x-www-form-urlencoded" \
     -d "client_id=[CLIENT_ID]" \
     -d "client_secret=[CLIENT_SECRET]" \
     -d "grant_type=client_credentials" \
     -d "box_subject_type=enterprise"  \
     -d "box_subject_id=[ENTERPRISE_ID]"
Java
BoxCCGAPIConnection api = BoxCCGAPIConnection.applicationServiceAccountConnection(
    "client_id",
    "client_secret",
    "enterprise_id"
);
Python
auth = CCGAuth(
  client_id="YOUR_CLIENT_ID",
  client_secret="YOUR_CLIENT_SECRET",
  enterprise_id="YOUR_ENETRPRISE_ID"
)
.NET
var boxConfig = new BoxConfigBuilder("YOUR_CLIENT_ID", "YOUR_CLIENT_SECRET")
                .Build();
var boxCCG = new BoxCCGAuth(boxConfig);
Node
const BoxSDK = require('box-node-sdk');
const sdkConfig = {
	boxAppSettings: {
		clientID: "CLIENT_ID",
		clientSecret: "CLIENT_SECRET"
	}, 
	enterpriseID: "ENTERPRISE_ID"
}
const sdk = BoxSDK.getPreconfiguredInstance(sdkConfig)

const client = sdk.getAnonymousClient();
iOS
import BoxSDK

let sdk = BoxSDK(clientId: "YOUR CLIENT ID HERE", clientSecret: "YOUR CLIENT SECRET HERE")
sdk.getCCGClientForAccountService(enterpriseId: "YOUR ENTERPRISE ID HERE") { result in
    switch result {
    case let .success(client):
        // Use client to make API calls
    case let .failure(error):
        // Handle error creating client
    }
}

If you would like to authenticate as an admin or a managed user:

  • set box_subject_type to user
  • set box_subject_id to the user ID
  • enable App + Enterprise Access and Generate User Access Tokens Box Developer Console
cURL
curl -i -X POST "https://api.box.com/oauth2/token" \
     -H "content-type: application/x-www-form-urlencoded" \
     -d "client_id=[CLIENT_ID]" \
     -d "client_secret=[CLIENT_SECRET]" \
     -d "grant_type=client_credentials" \
     -d "box_subject_type=user"  \
     -d "box_subject_id=[USER_ID]"

If you would like to authenticate as any application user:

  • set box_subject_type to user
  • set box_subject_id to the user ID
  • enable Generate User Access Tokens in the Box Developer Console
cURL
curl -i -X POST "https://api.box.com/oauth2/token" \
     -H "content-type: application/x-www-form-urlencoded" \
     -d "client_id=[CLIENT_ID]" \
     -d "client_secret=[CLIENT_SECRET]" \
     -d "grant_type=client_credentials" \
     -d "box_subject_type=user"  \
     -d "box_subject_id=[APPUSER_ID]"

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 either:

  • the client ID and client secret passed are incorrect or are not for the same application,

  • the box_subject_id cannot 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.

  • to use a box_subject_type of user, your application should be configured to generate user access tokens in the Advanced Features section of the Configuration tab.

    Generate access tokens check

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

  • your application has not been authorized in the Box Admin Console