Skip to main content
POST
/
oauth2
/
token
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 "code=[CODE]" \
     -d "grant_type=authorization_code"
{
  "access_token": "c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ",
  "expires_in": 3600,
  "token_type": "bearer",
  "restricted_to": [
    {
      "scope": "item_download",
      "object": {
        "id": "12345",
        "type": "folder",
        "etag": "1",
        "sequence_id": "3",
        "name": "Contracts"
      }
    }
  ],
  "refresh_token": "c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ",
  "issued_token_type": "urn:ietf:params:oauth:token-type:access_token"
}
This endpoint is in the version 2024.0. No changes are required to continue using it. For more details, see Box API versioning.Learn more about Box SDK versioning strategy.

Body

application/x-www-form-urlencoded

A request for a new OAuth 2.0 token.

​
grant_type
enum<string>
required

The type of request being made, either using a client-side obtained authorization code, a refresh token, a JWT assertion, client credentials grant or another access token for the purpose of downscoping a token.

Available options:
authorization_code,
refresh_token,
client_credentials,
urn:ietf:params:oauth:grant-type:jwt-bearer,
urn:ietf:params:oauth:grant-type:token-exchange
Example:

"authorization_code"

​
client_id
string

The Client ID of the application requesting an access token.

Used in combination with authorization_code, client_credentials, or urn:ietf:params:oauth:grant-type:jwt-bearer as the grant_type.

Example:

"ly1nj6n11vionaie65emwzk575hnnmrk"

​
client_secret
string

The client secret of the application requesting an access token.

Used in combination with authorization_code, client_credentials, or urn:ietf:params:oauth:grant-type:jwt-bearer as the grant_type.

Example:

"hOzsTeFlT6ko0dme22uGbQal04SBPYc1"

​
code
string<token>

The client-side authorization code passed to your application by Box in the browser redirect after the user has successfully granted your application permission to make API calls on their behalf.

Used in combination with authorization_code as the grant_type.

Example:

"n22JPxrh18m4Y0wIZPIqYZK7VRrsMTWW"

​
refresh_token
string<token>

A refresh token used to get a new access token with.

Used in combination with refresh_token as the grant_type.

Example:

"c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ"

​
assertion
string<jwt>

A JWT assertion for which to request a new access token.

Used in combination with urn:ietf:params:oauth:grant-type:jwt-bearer as the grant_type.

Example:

"xxxxx.yyyyy.zzzzz"

​
subject_token
string<token>

The token to exchange for a downscoped token. This can be a regular access token, a JWT assertion, or an app token.

Used in combination with urn:ietf:params:oauth:grant-type:token-exchange as the grant_type.

Example:

"c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ"

​
subject_token_type
enum<string>

The type of subject_token passed in.

Used in combination with urn:ietf:params:oauth:grant-type:token-exchange as the grant_type.

Available options:
urn:ietf:params:oauth:token-type:access_token
Example:

"urn:ietf:params:oauth:token-type:access_token"

​
actor_token
string<token>

The token used to create an annotator token. This is a JWT assertion.

Used in combination with urn:ietf:params:oauth:grant-type:token-exchange as the grant_type.

Example:

"c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ"

​
actor_token_type
enum<string>

The type of actor_token passed in.

Used in combination with urn:ietf:params:oauth:grant-type:token-exchange as the grant_type.

Available options:
urn:ietf:params:oauth:token-type:id_token
Example:

"urn:ietf:params:oauth:token-type:id_token"

​
scope
string<space_delimited_list>

The space-delimited list of scopes that you want apply to the new access token.

The subject_token will need to have all of these scopes or the call will error with 401 Unauthorized..

Example:

"item_upload item_preview base_explorer"

​
resource
string<url>

Full URL for the file that the token should be generated for.

Example:

"https://api.box.com/2.0/files/123456"

​
box_subject_type
enum<string>

Used in combination with client_credentials as the grant_type.

Available options:
enterprise,
user
Example:

"enterprise"

​
box_subject_id
string

Used in combination with client_credentials as the grant_type. Value is determined by box_subject_type. If user use user ID and if enterprise use enterprise ID.

Example:

"123456789"

​
box_shared_link
string<url>

Full URL of the shared link on the file or folder that the token should be generated for.

Example:

"https://cloud.box.com/s/123456"

Response

Returns a new Access Token that can be used to make authenticated API calls by passing along the token in a authorization header as follows Authorization: Bearer <Token>.

A token that can be used to make authenticated API calls.

​
access_token
string<token>

The requested access token.

Example:

"c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ"

​
expires_in
integer<int64>

The time in seconds by which this token will expire.

Example:

3600

​
token_type
enum<string>

The type of access token returned.

Available options:
bearer
Example:

"bearer"

​
restricted_to
Resource scope · object[]

The permissions that this access token permits, providing a list of resources (files, folders, etc) and the scopes permitted for each of those resources.

​
refresh_token
string<token>

The refresh token for this access token, which can be used to request a new access token when the current one expires.

Example:

"c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ"

​
issued_token_type
enum<string>

The type of downscoped access token returned. This is only returned if an access token has been downscoped.

Available options:
urn:ietf:params:oauth:token-type:access_token
Example:

"urn:ietf:params:oauth:token-type:access_token"