Please select which API documentation you would like to view:
SOAP
XML POST
Rest

Getting Started with the Box.net API

You can use the Box.net API to create applications and Web sites that integrate with Box.net. The Box.net API is a collection of Web services, which means that you can create Box Enabled applications using any modern programming language and operating system on any computer connected to the internet.

Box Enabled applications can perform the following functions:

• Store and retrieve files from Box.net
• Organize files into folders
• Move, rename and delete files
• Share files

Before you do anything, you'll need to sign up and obtain a Box.net API key, since you'll need to pass in your API key with every API call you make.

Every session with a Box Enabled application begins with user authentication, so we'll start there. For simplicity, we'll use the Box.net REST API, although you can also use the SOAP or XML Post APIs in your applications if you prefer -- the basic concepts are the same.

Box.net API authentication provides a secure way for users to authenticate with Box.net without having to share their Box.net user name or password with you. This provides a consistent, safe experience for users and makes things easier on you (since you don't have to store user credentials).

To obtain an authentication ticket, your application performs these steps:

• Obtain an authentication ticket by calling the get_ticket API method.
• Redirect the user to the Box.net API authentication page, passing the ticket you obtained from the get_ticket call as a query string parameter
• The user then authenticates by entering their user name and password on the authentication page
  

After the user has authenticated, the next step depends on whether you're writing a web application or a client application.

If you're writing a web application, Box.net redirects the user to a page called the callback page. This is a page that resides on your site (you should have designated this page when you set up your application). The authentication appends a ticket variable to the end of this URL, passing you a request that looks like this:

http://mysite.com/callback.php?ticket=ncnpjxt8bz7qkbn83c0qaf3ps0tr30tq&auth_token=98j243g9ijapwedfgjap8wj34gajw38w

After the user has been redirected to your callback page, you should store the auth_token value securely, since every API call your application makes from this point forward will require the application key and the authentication token to be passed in along with the call. (The ticket parameter is deprecated and only provided for backwards compatibility.)

For client applications, the user is shown a message instructing them to return to the application after they've authenticated. The application then calls get_auth_token with the ticket parameter to retrieve the authorization token.

At this point, you'll probably either want to show the user the files in their Box or enable them to upload a file to their Box.

To show a complete list of the user's files and folders, use the get_account_tree call. This call retrieves an XML document describing the entire contents of the user's box, including files and folders. You can also pass the ID of a folder as a parameter to this call, enabling your application to retrieve a subset of the tree structure.

To upload a file, your application performs an HTTP POST using a URL of the form:

http://upload.box.net/api/upload/<auth_token>/<folder_id>

At the time you upload a file using HTTP POST, you can also specify whether you want the file to be publicly sharable (as described in the Upload and Download reference documentation). You can also share a file after it's been uploaded using the public_share API if you prefer.