Getting Started

Box’s integrations connect the full Box experience to leading business applications. By integrating with Box, your application will be able to access Box content within your native experience.

With over 1,600+ integrations, developers have been building rich applications servicing a variety of use case including:

  • E-Signature
  • Forms
  • Data Loss Prevention
  • Information Right Management

This quickstart will take you through the basics of building a Box integration. By the end, you will have uploaded your first file to Box.

Authentication

When building an integration with the Box API, your app will access Box on behalf of your users. To do this, you'll need to have each user authenticate with Box to both verify their identify and grant your app permission to access the content stored in their Box account.

Box uses OAuth 2.0 for the purpose of authentication and authorization. The reason we use OAuth 2.0 is so that your app does not need to store or transmit a Box user's login credentials. OAuth also allows the user to authorize limited sets of permissions that can be revoked at any time.

Sample authentication flow

Sample authentication flow

Box provides a number of Web and Mobile SDKs to take care of the complicated parts of OAuth 2.0. We suggest using them to reduce complexity and streamline development.

Using the Box API

Now that you understand the components of building a Box integration, start making API calls to see what you can build. The quickest way to get started is to use a Developer Token to bypass the traditional OAuth setup and make a call within minutes. You can follow the steps below to create a developer token to start making live calls against our API

  1. Sign-up for a Box Developer Account. If you already have a Box account, click the Log In tab in the header.
  2. Create Your Application
  3. Select Create Developer Token (this token is valid for 60 minutes and only provides access to your account).

Access Your Root Folder

With the Developer Token, you can access your own Box account. Let's start with the basics of retrieving the contents of your account. You can retrieve the contents of any Box account by listing the contents of the root folder, which for every user is identified by ‘0’. Using cURL, we can do this like so:

curl https://api.box.com/2.0/folders/0 \
-H "Authorization: Bearer YOUR_DEVELOPER_TOKEN"
root_folder = client.folder(folder_id='0').get()
{
  "type": "folder",
  "id": "0",
  "sequence_id": null,
  "etag": null,
  "name": "All Files",
  "created_at": null,
  "modified_at": null,
  "description": "",
  "size": 0,
  "path_collection": {
    "total_count": 0,
    "entries": []
  },
  "created_by": {
    "type": "user",
    "id": "",
    "name": "",
    "login": ""
  },
  "modified_by": {
    "type": "user",
    "id": "277699565",
    "name": "Sanjay Padval",
    "login": "spadval+integration@box.com"
  },
  "trashed_at": null,
  "purged_at": null,
  "content_created_at": null,
  "content_modified_at": null,
  "owned_by": {
    "type": "user",
    "id": "277699565",
    "name": "Sanjay Padval",
    "login": "spadval+integration@box.com"
  },
  "shared_link": null,
  "folder_upload_email": null,
  "parent": null,
  "item_status": "active",
  "item_collection": {
    "total_count": 1,
    "entries": [
      {
        "type": "folder",
        "id": "7920153233",
        "sequence_id": "1",
        "etag": "1",
        "name": "Game of Thrones Recap"
      }
    ],
    "offset": 0,
    "limit": 100,
    "order": [
      {
        "by": "type",
        "direction": "ASC"
      },
      {
        "by": "name",
        "direction": "ASC"
      }
    ]
  }
}

Upload a File

Now that we’re able to see what’s in your root folder, let’s add some new files through the API. We need to do this as a multi-part form upload, which looks like this in cURL:

curl https://upload.box.com/api/2.0/files/content \
 -H "Authorization: Bearer YOUR_DEVELOPER_TOKEN" -X POST \
 -F attributes='{"name":"Jon_Snow.jpeg", "parent":{"id":"0"}}' \
 -F file=@Jon_Snow.jpeg

Alert:

Don’t forget the “@” sign when indicating the filename. This tells cURL to read data from the file.

Upon success, you’ll receive a response that should look like this:

{
  "total_count": 1,
  "entries": [
    {
      "type": "file",
      "id": "65344173073",
      "file_version": {
        "type": "file_version",
        "id": "68655777085",
        "sha1": "a242698061c76fce72675fbade6471ef11cb8346"
      },
      "sequence_id": "0",
      "etag": "0",
      "sha1": "a242698061c76fce72675fbade6471ef11cb8346",
      "name": "John_Snow.jpeg",
      "description": "",
      "size": 69726,
      "path_collection": {
        "total_count": 1,
        "entries": [
          {
            "type": "folder",
            "id": "0",
            "sequence_id": null,
            "etag": null,
            "name": "All Files"
          }
        ]
      },
      "created_at": "2016-05-13T14:36:30-07:00",
      "modified_at": "2016-05-13T14:36:30-07:00",
      "trashed_at": null,
      "purged_at": null,
      "content_created_at": "2016-05-13T14:36:30-07:00",
      "content_modified_at": "2016-05-13T14:36:30-07:00",
      "created_by": {
        "type": "user",
        "id": "277699565",
        "name": "Sanjay Padval",
        "login": "spadval+integration@box.com"
      },
      "modified_by": {
        "type": "user",
        "id": "277699565",
        "name": "Sanjay Padval",
        "login": "spadval+integration@box.com"
      },
      "owned_by": {
        "type": "user",
        "id": "277699565",
        "name": "Sanjay Padval",
        "login": "spadval+integration@box.com"
      },
      "shared_link": null,
      "parent": {
        "type": "folder",
        "id": "0",
        "sequence_id": null,
        "etag": null,
        "name": "All Files"
      },
      "item_status": "active"
    }
  ]
}

Download a File

Since we now have a file_id available, let’s try downloading that same file just to see how the process works. This is accomplished through a simple GET request to a /files resource like so:

curl -L https://api.box.com/2.0/files/65344173073/content
-H "Authorization: Bearer YOUR_DEVELOPER_TOKEN"

The response to this request will simply be the complete data of the file itself.

Next Steps

Congratulations! You've uploaded your first file to Box using our API. We recommend that you continue to use the Developer Token as you explore the other functionality of the Box Content API. Once you are ready, you can move on to the next tutorial where you will set up the OAuth 2.0 flow for your application.

Questions
If you have any questions, please visit our developer forum.

Getting Started