- Loading...
- No images or files uploaded yet.
|
|
|
To edit this page,
request access to the workspace. Already have an account? Log in! |
ApiAuthenticationBox.net Authentication
Every session with a Box application begins with user authentication, and must be handled from your application if you are not creating an OpenBox action. For simplicity, we will use the Box.net REST API, although you can also use the SOAP or XML Post APIs in your applications if you prefer -- the fundamental concepts are the same.
Box.net API authentication provides a secure way for users to authenticate with Box.net from other sites or applications without having to share their Box.net user name or password with third parties. This provides a consistent, safe experience for users and makes things easier on you (since you don't have to store user credentials).
To authenticate users you should apply the following steps:
get_ticket
input parameters: api_key: string output parameters: status: string, ticket: string Requestwww.box.net/api/1.0/rest?action=get_ticket&api_key=rrc1d3ntb53tt6b2vhail6rdtrsxov3v Response<?xml version='1.0' encoding='UTF-8'?> <response> <status>get_ticket_ok</status> <ticket>bxquuv025arztljze2n438md9zef95e8</ticket> </response> get_auth_token
input parameters: api_key: string, ticket: string, output parameters: status: string, auth_token: string, user: SOAPUser Requestwww.box.net/api/1.0/rest?action=get_auth_token&api_key=rrc1d3ntb53tt6b2vhail6rdtrsxov3v &ticket=udd863k39gn9mioc6ym2c6erbqm8qfsh Response<?xml version='1.0' encoding='UTF-8'?> <response> <status>get_auth_token_ok</status> <auth_token>9byo5bg8d2o3otp0voji0ej0v49bqcmo</auth_token> <user> <login>stas@itscript.com</login> <email>stas@itscript.com</email> <access_id>453</access_id> <user_id>453</user_id> <space_amount>2147483648</space_amount> <space_used>1024</space_used> </user> </response> authorization
input parameters: api_key: string, login: string, password: string, method: string output parameters: status: string, auth_token: string, user: SOAPUser
On successful authorization method will return 'logged' as status, sid is session id to use in other method calls, and SOAPUser which describes logged user.
If authorization wasn't successful, then status filed can be: 'invalid_login' when login or password is incorrect 'application_restricted' if you use an incorrect or restricted API key. Other fields will be empty.
Requestwww.box.net/api/1.0/rest?action=authorization&api_key=rrc1d3ntb53tt6b2vhail6rdtrsxov3v& login=email@example.com&password=1&method= Response<?xml version='1.0' encoding='UTF-8'?> <response> <status>logged</status> <auth_token>7umg20uoqv8bya5qj86txv8v7dmbrue0</auth_token> <user> <login>email@example.com</login> <email>email@example.com</email> <access_id>453</access_id> <user_id>453</user_id> <space_amount>2147483648</space_amount> <space_used>42782559</space_used> </user> </response> logout
input parameters: api_key: string, sid: string output parameters: status: string, On successful logout method will return 'logout_ok' as status. If logout wasn't successful, then status filed can be: 'invalid_auth_token' when auth_token is invalid.
Requestwww.box.net/api/1.0/rest?action=logout &api_key=3cdu8ivll9t1y6lz2m416xn6xstymzgg&auth_token=d2dqkrr6bae6ckua17osf9o1fhox9ypf Response<?xml version='1.0' encoding='UTF-8' ?> <response> <status>logout_ok</status> </response> register_new_user
input parameters: api_key: string, login: string, password: string output parameters: status: string, sid: string, user: SOAPUser If registration wasn't successful, status field can be: 'e_register', 'email_invalid', 'email_already_registered', 'application_restricted'.
Requestwww.box.net/api/1.0/rest?action=register_new_user&api_key=rrc1d3ntb53tt6b2vhail6rdtrsxov3v& login=email@example.com&password=123 Response<?xml version='1.0' encoding='UTF-8' ?> <response> <status>successful_register</status> <auth_token>29135479a888671e0dd6512df4f7a009</auth_token> <user> <login>email@example.com</login> <email>email@example.com</email> <access_id>398387</access_id> <user_id>398387</user_id> <space_amount>1073741824</space_amount> <space_used>0</space_used> </user> </response> register_paid_user
input parameters: api_key: string, login: string, password: string, name: string, plan: string, period: string, credit_card_first_name: string, credit_card_last_name: string, credit_card_street_address: string, credit_card_zip: string, credit_card_country: string, credit_card_number: string, credit_card_cvv: string, credit_card_exp_date: string output parameters: status: string, sid: string, user: SOAPUser If registration wasn't successful, status field can be: 'e_register', 'email_invalid', 'email_already_registered', 'credit_card_fields_error', 'wrong_billing_plan', 'wrong_billing_period', 'billing_error', 'application_restricted'.
Requestwww.box.net/api/1.0/rest?action=register_paid_user&api_key=rrc1d3ntb53tt6b2vhail6rdtrsxov3v& login=email%40example.com&password=123&name=John%20Doe&plan=Business&period=Year&credit_card_first_name=John& credit_card_last_name=Doe&credit_card_street_address=100%20Main%20Street&credit_card_zip=12345&credit_card_country=US& credit_card_number=0000000000000000&credit_card_cvv=111&credit_card_exp_date=1109 Response<?xml version='1.0' encoding='UTF-8' ?> <response> <status>successful_register</status> <auth_token>29135479a888671e0dd6512df4f7a009</auth_token> <user> <login>email@example.com</login> <email>email@example.com</email> <access_id>398387</access_id> <user_id>398387</user_id> <space_amount>1073741824</space_amount> <space_used>0</space_used> </user> </response> verify_registration_email
input parameters: api_key: string, login: string output parameters: status: string, Else status field can be: 'email_invalid', 'email_already_registered', 'application_restricted'.
Requestwww.box.net/api/1.0/rest?action=verify_registration_email&api_key=rrc1d3ntb53tt6b2vhail6rdtrsxov3v& login=email@example.com Response<?xml version='1.0' encoding='UTF-8' ?> <response> <status>email_ok</status> </response> get_account_tree
input parameters: api_key: string, sid: string, folder_id: long, params: ArrayOfString output parameters: status: string, tree: base64Binary
'folder_id' param defines root folder from which the tree begins. 'params' is array of string where you can set additional parameters, which are: onelevel - make a tree of one level depth, so you will get only files and folders stored in folder which folder_id you have provided. nofiles - include folders only in result tree, no files. nozip - do not zip tree xml.
On successful result you will receive 'listing_ok' as status and base64 encoded zipped tree xml. So you have to decode the received tree, then unzip it (if you haven't set 'nozip' param) and you will get xml like this: (note that updatedand createdare UNIX timestamps in PST) <?xml version="1.0" ?> <folder id="0" name="" shared="0"> <tags></tags> <files></files> <folders> <folder id="4384" name="Incoming" shared="0"> <tags> <tag id="34" /> </tags> <files> <file id="68736" file_name="cows.w3g" keyword="" shared="0" size="232386" created="1129537520" updated="1129537520"> <tags> </tags> </file> <file id="68737" file_name="silver.html" keyword="" shared="0" size="15805" created="1129537520" updated="1129537520"> <tags> <tag id="35" /> </tags> </file> </files> </folder> <folders> </folder> 'not_logged_id', 'application_restricted', 'e_folder_id'
Requestwww.box.net/api/1.0/rest?action=get_account_tree&api_key=rrc1d3ntb53tt6b2vhail6rdtrsxov3v &auth_token=263gtmxiy8k8o2ebzs41pilbubvpn91g&folder_id=0¶ms[]=nozip Response<?xml version='1.0' encoding='UTF-8'?> <response> <status>listing_ok</status> <tree> <folder id="0" name="" shared="0"> <tags></tags> <files></files> <folders> <folder id="4384" name="Incoming" shared="0"> <tags> <tag id="34" /> </tags> <files> <file id="68736" file_name="cows.w3g" keyword="" shared="0" size="232386" created="1129537520" updated="1129537520"> <tags> </tags> </file> <file id="68737" file_name="silver.html" keyword="" shared="0" size="15805" created="1129537520" pdated="1129537520"> <tags> <tag id="35" /> </tags> </file> </files> </folder> <folders> </folder> </tree> </response> export_tags
input parameters: api_key: string, sid: string output parameters: status: string, tag_xml: base64Binary,
On successful a result, you will receive 'export_tags_ok' and tag_xml will be base64 encoded tags xml. After decoding tag_xml you will get xml like this:
<?xml version="1.0"?> <tags> <tag id="37"> music </tag> <tag id="38"> mp3 </tag> </tags> not_logged_id, application_restricted
Requestwww.box.net/api/1.0/rest?action=export_tags&api_key=rrc1d3ntb53tt6b2vhail6rdtrsxov3v &auth_token=z35bqm6o87ry4k02eug3r3yhrfsc5del Response<?xml version='1.0' encoding='UTF-8'?> <response> <status>export_tags_ok</status> <tags> <tag id="37">tag1</tag> <tag id="38">tag2</tag> </tags> </response> create_folder
input parameters: api_key: string, sid: string, parent_id: long, name: string, share: long output parameters: status: string, folder: SOAPFolder
'parent_id' param is the id of a folder in which a new folder will be created, 'name' param is the name of a new folder. Set 'share' to 1 if you want to share a folder publicly.
On a successful result, the status will be 'create_ok'.
If the result wasn't successful, status field can be: 'e_no_parent_folder', 'not_logged_in', 'application_r'stricted'
Requestwww.box.net/api/1.0/rest?action=create_folder&api_key=rrc1d3ntb53tt6b2vhail6rdtrsxov3v &auth_token=5oahsklt4x0emkj1rdzm3nug1aq81t9k&parent_id=0&name=New%20Folder&share=1 Response<?xml version='1.0' encoding='UTF-8'?> <response> <status>create_ok</status> <folder> <folder_id>738</folder_id> <folder_name>New Folder</folder_name> <folder_type_id>0</folder_type_id> <user_id>453</user_id> <path></path> <shared>1</shared> <public_name>gh23ghjj</public_name> <show_comments></show_comments> <parent_folder_id>0</parent_folder_id> <password></password> </folder> </response> move
input parameters: api_key: string, sid: string, target: string, target_id: long, destination_id: long output_parameters: status: string
'target' param can be either 'file' or 'folder' depending on what do you want to move, 'target_id' is the id of a file or folder to be moved, 'destination_id' is the destination folder id.
On a successful result, status will be 's_move_node'. If the result wasn't successful, status field can be: 'e_move_node', 'not_logged_in', 'application_restricted'
Requestwww.box.net/api/1.0/rest?action=move&api_key=rrc1d3ntb53tt6b2vhail6rdtrsxov3v &auth_token=19x43ykyo3bnefz75yyuepxgm6o4rf7a&target=folder&target_id=739&destination_id=738 Response<?xml version='1.0' encoding='UTF-8'?> <response> <status>s_move_node</status> </response> rename
input parameters: api_key: string, sid: string, target: string, target_id: long, new_name: string output parameters: status: string
'target' param can be either 'file' or 'folder' depending on what you want to rename, 'target_id' is the id of a file or folder to be renamed, 'new_name' is the new name for a file or folder.
On a successful result, status will be 's_rename_node'. If result wasn't successful, stat's field can be: 'e_rename_node', 'not_logged_in', 'application_restricted'
Requestwww.box.net/api/1.0/rest?action=rename&api_key=rrc1d3ntb53tt6b2vhail6rdtrsxov3v &auth_token=bhpcsgorohv70rrkcf5so19vrapuznla&target=folder&target_id=739&new_name=New%20Name Response<?xml version='1.0' encoding='UTF-8'?> <response> <status>s_rename_node</status> </response> delete
input parameters: api_key: string, sid: string, target: string, target_id: long output parameters: status: string
'target' param can be either 'file' or 'folder' depending on what you want to delete, 'target_id' is id of a file or folder to be deleted.
On a successful result, the status will be 's_delete_node'. If the result wasn't successful, status field can be: 'e_delete_node', 'not_logged_in', 'application_restricted'
Requestwww.box.net/api/1.0/rest?action=delete&api_key=rrc1d3ntb53tt6b2vhail6rdtrsxov3v& auth_token=tkm1l2ojyhgrf86zzvdqvoa6zcqss6pf&target=folder&target_id=738 Response<?xml version='1.0' encoding='UTF-8'?> <response> <status>s_delete_node</status> </response> public_share
input parameters: api_key: string, sid: string, target: string, target_id: long, password: string, message: string, emails: ArrayOfString, output parameters: status: string, public_name: string
On a successful result, the status will be 'share_ok' and 'public_name' param will be a unique identifier of a publicly shared file or folder. If the result wasn't successful, the status field can be: 'share_error', 'wrong_node', 'not_logged_in', 'application_restricted'
Requestwww.box.net/api/1.0/rest?action=public_share&api_key=rrc1d3ntb53tt6b2vhail6rdtrsxov3v &auth_token=rpuis3lincpbyz60gyym8s3xhnc6gbcl&target=folder&target_id=709&password= &message=hey&emails[]=email@example.com&emails[]=email2@example.com Response<?xml version='1.0' encoding='UTF-8'?> <response> <status>share_ok</status> <public_name>ojf3i2n100</public_name> </response> public_unshare
input parameters: api_key: string, sid: string, target: string, target_id: long output parameters: status: string
On a successful result, the status will be 'unshare_ok'. If the result wasn't successful, the status field can be: 'unshare_error', 'wrong_node', 'not_logged_in', 'application_restricted'
Requestwww.box.net/api/1.0/rest?action=public_unshare&api_key=rrc1d3ntb53tt6b2vhail6rdtrsxov3v& auth_token=j8eu39sn43pmso00au856izbndae5oom&target=folder&target_id=709 Response<?xml version='1.0' encoding='UTF-8'?> <response> <status>unshare_ok</status> </response> private_share
input parameters: api_key: string, sid: string, target: string, target_id: long, emails: ArrayOfString, message: string, notify: boolean output parameters: status: string
Note: currently only files can be shared privately.
On a successful result, the status will be 'private_share_ok'. If the result wasn't successful, the status field can be: 'private_share_error', 'wrong_node', 'not_logged_in', 'application_restricted'
Requestwww.box.net/api/1.0/rest?action=private_share&api_key=rrc1d3ntb53tt6b2vhail6rdtrsxov3v &auth_token=7pdreq6aqtq7udn986mxnp8lpq1ol0ec&target=folder&target_id=4935 &emails[]=email@example.com&message=hey¬ify=true Response<?xml version='1.0' encoding='UTF-8'?> <response> <status>private_share_ok</status> </response> add_to_mybox
input parameters: api_key: string, sid: string, file_id: long, public_name: string, folder_id: long, tags: string output parameters: status: string
On a successful result, the status will be 'addtomybox_ok'. If the result wasn't successful, the status field can be: 'addtomybox_error', 'not_logged_id', 'application_restricted', 's_link_exists'
Requestwww.box.net/api/1.0/rest?action=add_to_mybox&api_key=rrc1d3ntb53tt6b2vhail6rdtrsxov3v &auth_token=a3ysjive1k2x1q82bme6pxhngqh9ryrn&file_id=4940&public_name=&folder_id=0 &tags[]= Response<?xml version='1.0' encoding='UTF-8'?> <response> <status>addtomybox_ok</status> </response> add_to_tag
input parameters: api_key: string, sid: string, tags: ArrayOfString, target: string, target_id: long output parameters: status: string
On successful a result, you will receive 'addtotag_ok'. If the result wasn't successful, status field can be: addtotag_error
Requestwww.box.net/api/1.0/rest?action=add_to_tag&api_key=p6eu1n2tblaeebnfkyby4gfkg6mrz0xp &auth_token=qydz66sfc6pqb2mnk565izn5m870ghs2&tags[]=test_tag&tags[]=test_tag1&target=file &target_id=6343 Response<?xml version='1.0' encoding='UTF-8' ?> <response> <status>addtotag_ok</status> </response> get_file_info
input parameters: api_key: string, sid: string, file_id: long output parameters: status: string, info: SOAPFileInfo
On successful a result, you will receive status 's_get_file_info' and file info in 'info'. If the result wasn't successful, status field can be: e_access_denied
Requestwww.box.net/api/1.0/rest?action=get_file_info&api_key=rrc1d3n4b53tt6b2vh1il6tdtrsxov3v& auth_token=8sdevidfoatqdn39qu6ke7f10nlp4njv&file_id=224 Response<?xml version='1.0' encoding='UTF-8' ?> <response><status>s_get_file_info</status> <info> <file_id>224</file_id> <file_name>Box Press Release.doc</file_name> <folder_id>0</folder_id> <shared>0</shared> <shared_name></shared_name> <size>22528</size> <description></description> <sha1>9a0bc49038c167151c544ac0b5fc9042335a41a3</sha1> <created>1182159570</created> <updated>1182159571</updated> </info> </response> set_description
input parameters: api_key: string, sid: string, target: string, target_id: login, description: string output parameters: status: string
On successful a result, you will receive status 's_set_description'. If the result wasn't successful, status field can be: e_set_description
Requestwww.box.net/api/1.0/rest?action=set_description&api_key=rrc1d3n4b53tt6b2vh1il6tdtrsxov3v& auth_token=6sx9xnm2z6vgjxx3xpvsea2p9oth8le2&target=file&target_id=224&description=123 Response<?xml version='1.0' encoding='UTF-8' ?> <response> <status>s_set_description</status> </response> get_friends
input parameters: api_key: string, sid: string, params: ArrayOfString output parameters: status: string, friends: base64Binary
'params' is an array of the string where you can set additional parameters, which are: nozip - do not zip tree xml.
On a successful result you will receive 's_get_friends' as the status and base64 encoded (and zipped) friends xml. Friends xml looks like this:
<friends> <friend> <name>email2@example.com</name> <email>email2@example.com</email> <accepted>1</accepted> <avatar_url> http://box.net/index.php?rm=box_user_avatar&user_id=398396 &width=40&height=40&type=large </avatar_url> <boxes> <box> <id>15</id> <url>http://box.net/p/email2</url> <status>0</status> </box> </boxes> <subscriptions> <subscription> <box_id>14</box_id> <user_name>email3@example.com</user_name> <url>http://box.net/p/email3</url> <status>subscribed</status> </subscription> </subscriptions> </friend> </friends> e_get_friends
Requestwww.box.net/api/1.0/rest?action=get_friends&api_key=rrc1d3n4b53tt6b2vh1il6tdtrsxov3v &auth_token=ekp2t8vb8l1spb1mnonlqmgztkrq1rtl¶ms[]=nozip Response<?xml version='1.0' encoding='UTF-8' ?> <response> <status>s_get_friends</status> <friends> <friends> <friend> <name>email2@example.com</name> <email>email2@example.com</email> <accepted>1</accepted> <avatar_url> http://box.net/index.php?rm=box_user_avatar&user_id=398396 &width=40&height=40&type=large </avatar_url> <boxes> <box> <id>15</id> <url>http://box.net/p/email2</url> <status>0</status> </box> </boxes> <subscriptions> <subscription> <box_id>14</box_id> <user_name>email3@example.com</user_name> <url>http://box.net/p/email3</url> <status>subscribed</status> </subscription> </subscriptions> </friend> </friends> </response> request_friends
input parameters: api_key: string, sid: string, emails: ArrayOfString, message: string, params: ArrayOfString output parameters: status: string 'emails' - array of emails. 'message' - text message that you want to send to freinds. 'params' is an array of string where you can set additional parameters, which are: box_auto_subscribe - subscribe to public boxes of inveted users. no_email - don't send emails to invited users.
On a successful result, you will receive status 's_request_friends'. If the result wasn't successful, status field can be: e_request_friends
Requestwww.box.net/api/1.0/rest?action=request_friends&api_key=rrc1d3n4b53tt6b2vh1il6tdtrsxov3v &auth_token=i4od3dv74uvdder7ng8vn5vbu90clu4t&emails[]=email1%40example.com &emails[]=email2%40example.com&message=123¶ms[]=auto_subscribe ¶ms[]=no_email Response<?xml version='1.0' encoding='UTF-8' ?> <response> <status>s_request_friends</status> </response> get_updates
input parameters: api_key: string, sid: string, begin_timestamp: long, params: ArrayOfString output parameters: status: string, updates: base64Binary 'begin_timestamp' - the start date in unix timestamp of the range of updates you wish to retrieve. 'params' is array of string where you can set additional parameters, which are: nozip - do not zip tree xml.
On successful result you will receive 's_get_updates' as status and base64 encoded(and zipped) updates xml. Updates xml looks like this:
<updates> <update> <name></name> <message></message> <updated>1180341648</updated> <user_name>email1@example.xom</user_name> <public_url>http://box.net/p/email1</public_url> <files> <file> <name></name> <size>293.5 KB</size> <date>May 28, 2007</date> <thumbnail> http://dav1.box.net/large_thumb/2007-05-28/b711d51b95bd 888ada7a46999b3d2b70.jpg </thumbnail> </file> </files> </update> </updates> e_get_updates
Requestwww.box.net/api/1.0/rest?action=get_updates&api_key=rrc1d3n4b53tt6b2vh1il6tdtrsxov3v &auth_token=6d4f3clzijzuodjczxnenfu68q1jmqi2&begin_timestamp=0 ¶ms[]=nozip Response<?xml version='1.0' encoding='UTF-8' ?> <response> <status>s_get_updates</status> <updates> <updates> <update> <name></name> <message></message> <updated>1180341648</updated> <user_name>email1@example.xom</user_name> <public_url>http://box.net/p/email1</public_url> <files> <file> <name></name> <size>293.5 KB</size> <date>May 28, 2007</date> <thumbnail> http://dav1.box.net/large_thumb/2007-05-28/b711d51b95bd 888ada7a46999b3d2b70.jpg </thumbnail> </file> </files> </update> </updates> </updates> </response> Upload & Download
DownloadTo download a file, use a link like http://box.net/api/1.0/download/<auth_token>/<file_id>for example: http://box.net/api/1.0/download/0ef4e2b1be630554ffa4044c054b1954/542666 UploadTo upload a file, send HTTP POST request to http://upload.box.net/api/1.0/upload/<auth_token>/<folder_id>
It is important that you upload to upload.box.net otherwise your upload will be rejected.
folder_id is the id of a folder in which the file will be uploaded.
For public sharing of file set share, message and emails fields. HTML to perform an upload might look like the following:
<form action="http://upload.box.net/api/1.0/upload/0ef4e2b1be630554ffa4044c054b1954/756" enctype="multipart/form-data" method="POST"> <input type="file" name="new_file1" /> <input type="file" name="new_file2" /> <input type="text" name="share" value="1" /> <input type="text" name="message" value="Hello" /> <input type="text" name="emails[]" value="test@domain.com" /> <input type="text" name="emails[]" value="test1@domain.com" /> <input type="submit" name="upload_files" value="Upload File" /> </form>
<?xml version='1.0' encoding='UTF-8' ?> <response> <status>upload_ok</status> <files> <file file_name="read_me.txt" id="5996" folder_id="756" shared="0" public_name="" /> <file file_name="Rally.avi" error="filesize_limit_exceeded" /> </files> </response> 'upload_some_files_failed', 'not_logged_id', 'application_restricted'
For files that wasn't upload error field can be: not_enough_free_space, filesize_limit_exceeded, access_denied After the user has authenticated, the next step depends on whether you're writing a web application or a client application. Web Applications
If you're writing a web application, Box.net can redirect the user to a page that you specify (the "Redirect url" that you can define within your OpenBox service).
The authentication appends a ticket variable to the end of this URL, passing you a request that looks like this:
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.
Desktop Applications
For desktop applications, the user is shown a message instructing them to return to the application after they have authenticated your application to access Box. Your application can then call get_auth_token with the ticket parameter to retrieve the authorization token. You may want to present a button or other prompt on your application for the user to notify you of a successful authentication, so that you know when to call the 'get_auth_token' method.
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.
Need additional assistance? Please feel free to Contact us ApiAuthentication
|
Anonymous
Create an account or Log in
Documentation Home
Developers Blog
Project Setup page
OpenBox Actions:
Introduction to OpenBox Actions
Creating Actions
Action Parameters
Popup Actions - Client Callback
API Introduction:
Getting started with the API
Authenticating Users
Using REST
Using SOAP
Using XML-RPC
Sample code and libraries
API Functions:
Authentication
get_ticket
get_auth_token
logout
register_new_user
verify_registration_email
get_account_info
File & Folder Operations
get_account_tree
create_folder
move
copy
rename
delete
get_file_info
set_description
Sharing
public_share
public_unshare
private_share
request_friends
get_friends
add_to_mybox
Tags
add_to_tag
export_tags
Download & Upload methods