BObox
Authorization

Request access token

Request an Access Token using either a client-side obtained OAuth 2.0 authorization code or a server-side JWT assertion.

An Access Token is a string that enables Box to verify that a request belongs to an authorized session. In the normal order of operations you will begin by requesting authentication from the authorize endpoint and Box will send you an authorization code.

You will then send this code to this endpoint to exchange it for an Access Token. The returned Access Token can then be used to to make Box API calls.

post/oauth2/token

Request

  • Base URL
    https://api.box.com
  • URL
    https://api.box.com/oauth2/token
  • Auth
    none required

Request body application/x-www-form-urlencoded

grant_type'authorization_code' | 'refresh_token' | 'client_credentials' | 'urn:ietf:params:oauth:grant-type:jwt-bearer' | 'urn:ietf:params:oauth:grant-type:token-exchange' urn 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.

client_idstring

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.

client_secretstring

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.

codestring 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.

refresh_tokenstring token

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

Used in combination with refresh_token as the grant_type.

assertionstring 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.

subject_tokenstring 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.

subject_token_type'urn:ietf:params:oauth:token-type:access_token'

The type of subject_token passed in.

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

actor_tokenstring 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.

actor_token_type'urn:ietf:params:oauth:token-type:id_token' urn

The type of actor_token passed in.

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

scopestring 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..

resourcestring url

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

box_subject_type'enterprise' | 'user'

Used in combination with client_credentials as the grant_type.

box_subject_idstring

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.

box_shared_linkstring url

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

Example request

{
  "grant_type": "authorization_code",
  "client_id": "ly1nj6n11vionaie65emwzk575hnnmrk",
  "client_secret": "hOzsTeFlT6ko0dme22uGbQal04SBPYc1",
  "code": "n22JPxrh18m4Y0wIZPIqYZK7VRrsMTWW",
  "refresh_token": "c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ",
  "assertion": "xxxxx.yyyyy.zzzzz",
  "subject_token": "c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ",
  "subject_token_type": "urn:ietf:params:oauth:token-type:access_token",
  "actor_token": "c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ",
  "actor_token_type": "urn:ietf:params:oauth:token-type:id_token",
  "scope": "item_upload item_preview base_explorer",
  "resource": "https://api.box.com/2.0/files/123456",
  "box_subject_type": "enterprise",
  "box_subject_id": "123456789",
  "box_shared_link": "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>.

access_tokenstring token

The requested access token.

expires_ininteger

The time in seconds by which this token will expire.

token_type'bearer'

The type of access token returned.

refresh_tokenstring token

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

issued_token_type'urn:ietf:params:oauth:token-type:access_token' urn

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

Example response

{
  "access_token": "c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ",
  "expires_in": 3600,
  "token_type": "bearer",
  "restricted_to": [
    {
      "scope": "item_download",
      "object": {
        "id": "12345",
        "etag": "1",
        "type": "folder",
        "sequence_id": "3",
        "name": "Contracts"
      }
    }
  ],
  "refresh_token": "c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ",
  "issued_token_type": "urn:ietf:params:oauth:token-type:access_token"
}

Changes

No recorded changes to this operation across all 2 revisions of this API.