Manage Applications

    Request an access token

    post
    https://api.box.com
    /oauth2/token

    Request an Access Token using either a client-side obtained OAuth2 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.

    Request

    application/x-www-form-urlencoded

    Request Body

    string / tokenin bodyoptional
    c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ

    The actor 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.

    string / urnin bodyoptional
    urn:ietf:params:oauth:token-type:id_token

    Value is always "urn:ietf:params:oauth:token-type:id_token"

    string / jwtin bodyoptional
    xxxxx.yyyyy.zzzzz

    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.

    stringin bodyoptional
    ly1nj6n11vionaie65emwzk575hnnmrk

    The Client ID of the application requesting an access token.

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

    stringin bodyoptional
    hOzsTeFlT6ko0dme22uGbQal04SBPYc1

    The client secret of the application requesting an access token.

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

    string / tokenin bodyoptional
    n22JPxrh18m4Y0wIZPIqYZK7VRrsMTWW

    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.

    string / urnin bodyrequired
    authorization_code

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

    Value is one of "authorization_code", "refresh_token", "urn:ietf:params:oauth:grant-type:jwt-bearer", "urn:ietf:params:oauth:grant-type:token-exchange"

    string / tokenin bodyoptional
    c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ

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

    Used in combination with refresh_token as the grant_type.

    string / urlin bodyoptional
    https://api.box.com/2.0/files/123456

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

    string / space_delimited_listin bodyoptional
    item_upload item_preview base_explorer

    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.

    string / tokenin bodyoptional
    c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ

    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.

    stringin bodyoptional
    urn:ietf:params:oauth:token-type:access_token

    Value is always "urn:ietf:params:oauth:token-type:access_token"

    Response

    application/jsonAccess Token

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

    application/jsonOAuth2 Error

    An authentication error.

    You can now try out some of our APIs live, right here in the documentation.
    Log In

    Request Example

    cURL
    curl -X POST https://api.box.com/oauth2/token \
         -H "Content-Type: application/x-www-form-urlencoded" \
         -d '{
           "client_id": "<CLIENT_ID>",
           "client_secret": "<CLIENT_SECRET>",
           "code": "<CODE>",
           "grant_type": "authorization_code"
         }'
    Python
    from boxsdk import Client
    
    # Make sure that the csrf token you get from the `state` parameter
    # in the final redirect URI is the same token you get from the
    # get_authorization_url method to protect against CSRF vulnerabilities.
    assert 'THE_CSRF_TOKEN_YOU_GOT' == csrf_token
    access_token, refresh_token = oauth.authenticate('YOUR_AUTH_CODE')
    client = Client(oauth)

    Response Example

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