vBoxxCloud API and Authentication reference

The vBoxxCloud API gives you the ability to harness vBoxxCloud directly. The API allows you to securely read and write files, create/edit/delete accounts and organizations, update and view activity, access and create roots, and retrieve machine information. All of the functionality of vBoxxCloud is at your fingertips through the vBoxxCloud API.

The new vBoxxCloud API 2 is available here.

You can also find the vBoxxCloud authentication reference here.

Getting Started

To access any files, we need to know who you are so we know what permissions you have. To do that, you post your username/password to our auth URL, and it will give you a token that you can pass to other methods. The primary URLs needed are the same as the Dropbox API's account/info and metadata URLs.

Getting API Token

To get the API token, the HTTP POST request must contain the username and password for authentication, the session API token is served up with success or an error message is displayed.

For example, suppose your server is hosted at web.vboxx.nl. To request a session token provide your username and password as POSTING variables in the following URL (note the use of the /1/, which is the API version number):

     https://web.vboxx.nl/1/auth?username=&password=

A successful response looks like this:

{
    "success":true,
    "session_token":                                                                 "GWObmeSrkWxGtCje0Mv27PcIkkwMydPSrY2d8yksfjonP7jg6eHgscUrBtMnoV584FFCyQPGXbHyetKmjWvBVIppUqQirBUVZCeJnLoIJgtabS4jyl1zsrcimqJCp7RY"
}

Omitting the username and password posting variables results in this error:

{
     "message": "You must provide a username and password",
     "success": false
}

Whilst an incorrect username and password pair will result in this error:

{
     "message": "Invalid username or password",
     "success": false
}

The API token is good for the current session only and a new one is needed for each session. Additionally, create, read, update, and delete functionality is limited to the scope of the API token requester. For example, if a system admin requests an API token, she has access to all organizations and actions therein. But if a user requests an API token, she is barred from creating new organizations, setting policies, and otherwise altering organizational level content.

Let's take a look at some examples of what we can do with the token.

Get Account Info

To grab the account information for the current user (i.e. the API token requester) use the URL format /1/account/info/ . The full URL request will look like this (using the example IP for the host above)

     http://web.vboxx.nl/1/account/info/?session_token=DFx9Hm5K2IQ8PK2s5Qwd5gY72EyHblYKbJSRhk04QxkyYl7nRptnE0psCjKtElPkKRjvXl0O6uzekLj6x3YWX6M9aSPQFrx5iVqHigoofeTu6PJoeWTfwJFbjCN625sv

The response will look something like this:

{
     "id": 1, 
     "first_name": "Karel", 
     "last_name": "de Groot", 
     "display_name": "Karel ",
     "email": "karel.degroot@gmail.com" 
     "root_id": 1, 
     "space_usage": 3169361, 
     "space_usage_formatted": "3.02M", 
     "space_quota": null, 
     "space_quota_formatted": null, 
     "roots": 
     [ {
     "type": "backup", 
     "space_used": 718334, 
     "id": 4, 
     "name": "C:\\Projects\\backups\\greensnake\\greensnake\\static\\images" 
     }, {
     "type": "backup", 
     "space_used": 150048, 
     "id": 5, 
     "name": "C:\\Projects\\dropdav" 
     }, {
     "type": "backup", 
     "space_used": 1596688, 
     "id": 6, 
     "name": "C:\\Projects\\wsgidav" 
     }, {
     "type": "sync", 
     "space_used": 704291, 
     "id": 1, 
     "name": "Files" 
     }, {
     "type": "share", 
     "space_used": 0, 
     "id": 2, 
     "name": "Team Share 1" 
     }, {
     "type": "share", 
     "space_used": 0, 
     "id": 3, 
     "name": "Team Share 2" 
     }
     ], 
     "success": true,
}

List files & folders in a root

To list files and folders in the default root (i.e. the files/folders in the Sync Folder), use the following URL GET request:

     http://web.vboxx.nl/1/metadata/1/?session_token=DFx9Hm5K2IQ8PK2s5Qwd5gY72EyHblYKbJSRhk04QxkyYl7nRptnE0psCjKtElPkKRjvXl0O6uzekLj6x3YWX6M9aSPQFrx5iVqHigoofeTu6PJoeWTfwJFbjCN625sv

This will have a response like this:

{
"hash": "71595dc2e15ae7b9924b60662f166108ccc588c3", 
"rev": 0, 
"thumb_exists": false, 
"modified_unix_timestamp": 0, 
"path": "/", 
"is_dir": true, 
"client_mtime": 0, 
"size": "0B", 
"is_deleted": false, 
"bytes": 0, 
"modified": 0, 
"contents": [ {
"rev": 0, 
"thumb_exists": false, 
"modified_unix_timestamp": 0, 
"path": "/documents", 
"is_dir": true, 
"client_mtime": 0, 
"size": "0B", 
"is_deleted": false, 
"bytes": 0, 
"modified": 0, 
"icon": "folder", 
"root": 1
}, {
"rev": 0, 
"thumb_exists": false, 
"modified_unix_timestamp": 0, 
"path": "/pictures", 
"is_dir": true, 
"client_mtime": 0, 
"size": "0B", 
"is_deleted": false, 
"bytes": 0, 
"modified": 0, 
"icon": "folder", 
"root": 1
}, {
"rev": 10, 
"thumb_exists": false, 
"modified_unix_timestamp": 1353459846, 
"path": "/vBoxxCloud.jpg", 
"is_dir": false, 
"client_mtime": "2012-11-20T17:04:06", 
"size": "1.91k", 
"is_deleted": false, 
"bytes": 1953, 
"modified": "2012-11-20T17:04:06", 
"icon": "page_white_picture", 
"root": 1
}
], 
"status_code": 200, 
"icon": "folder", 
"root": 1
}

List files & folders in a directory of a given root

To list files and folders in a directory of your specifying use the following URI formatting: /1/metadata/*root_id*/*path*/>session_token=*session_token*. Here's an example:

     http://web.vboxx.nl/1/metadata/1/documents/?session_token=DFx9Hm5K2IQ8PK2s5Qwd5gY72EyHblYKbJSRhk04QxkyYl7nRptnE0psCjKtElPkKRjvXl0O6uzekLj6x3YWX6M9aSPQFrx5iVqHigoofeTu6PJoeWTfwJFbjCN625sv

Here the default root (/1/) is specified, and the "documents" folder is in the default root.

Create share and download links

To create a share link to an entire root use this URI:

     http://web.vboxx.nl/1/shares/create_link/1/?session_token=DFx9Hm5K2IQ8PK2s5Qwd5gY72EyHblYKbJSRhk04QxkyYl7nRptnE0psCjKtElPkKRjvXl0O6uzekLj6x3YWX6M9aSPQFrx5iVqHigoofeTu6PJoeWTfwJFbjCN625sv

To create a share link to a folder within a root:

     http://web.vboxx.nl/1/shares/create_link/1/documents/?session_token=DFx9Hm5K2IQ8PK2s5Qwd5gY72EyHblYKbJSRhk04QxkyYl7nRptnE0psCjKtElPkKRjvXl0O6uzekLj6x3YWX6M9aSPQFrx5iVqHigoofeTu6PJoeWTfwJFbjCN625sv

To create a share link to a specific file in a folder in a root:

     http://web.vboxx.nl/1/shares/create_link/1/documents/abc.txt?session_token=DFx9Hm5K2IQ8PK2s5Qwd5gY72EyHblYKbJSRhk04QxkyYl7nRptnE0psCjKtElPkKRjvXl0O6uzekLj6x3YWX6M9aSPQFrx5iVqHigoofeTu6PJoeWTfwJFbjCN625sv

To create a link to download a specific file:

     http://web.vboxx.nl/1/files/1/documents%2Fabc.txt?session_token=DFx9Hm5K2IQ8PK2s5Qwd5gY72EyHblYKbJSRhk04QxkyYl7nRptnE0psCjKtElPkKRjvXl0O6uzekLj6x3YWX6M9aSPQFrx5iVqHigoofeTu6PJoeWTfwJFbjCN625sv

Implemented Endpoints

Base URI:
//management/

Error responses will look like the following and will have a HTTP response code matching the status_code :

{
    "status_code": 404,
    "message": "unknown root with id 20",
    "code": "error" 
}

{
    "status_code": 500,
    "message": "missing required field activity_type_id",
    "code": "error" 
}

Person

/person/ - retrieves information for the current user
/person// - retrieves information for the user with the specified id, if the current user has permission
/person//full/ - retrieves "full" information for the user with the specified id, if the current user has permission. for example is that the company is populated instead of just returning the company's id

/person/create/- creates a new person with the following parameters:

Name	Required	Info
company_id	yes	company id for the new person
first_name	yes	new person's first name
last_name	yes	new person's last name
email	yes	new person's email address
password	yes	new person's password
space_quota	no	integer representation of the new user's space quota
mobile_phone	no	new user's mobile phone number
mobile_service_provider_id	no	new user's mobile service provider id
site_admin	no	true or false to give the new user site_admin privileges
system_admin	no	true or false to give the new user system_admin privileges
create_root	no	true or false to have a root automatically created for the new user

sample successful response:

{
    "full_uri": "/1/management/person/31/full/",
    "root_created": false,
    "code": "success",
    "id": 31,
    "uri": "/1/management/person/31/" 
}

/person/update/- updates an existing person with the following parameters (id is the only required parameter):

Name

id

first_name

last_name

company_id

space_quota

email

password

mobile_phone

mobile_service_provider_id

system_admin

site_admin

sample successful response:

{
    "full_uri": "/1/management/person/31/full/",
    "code": "success",
    "id": 31,
    "uri": "/1/management/person/31/" 
}

Activity

/activity/types/ - lists the types of activities in the system
sample response:

[
    {
        "id": 1,
        "activity": "added account",
        "machine_scope": false,
        "user_scope": false,
        "system_scope": false
    },
    {
        "id": 10,
        "activity": "added auth source to",
        "machine_scope": false,
        "user_scope": false,
        "system_scope": false
    },
    ....
}

/activity/// - returns the activities for an entity_type of "organization" or "person" with the specified id. Returns up to 10 activities along with the total activities, current page number, and number of pages. see sample response below
/activity///page// - same as above, but returns page_name of the paged activity results, instead of page 1
sample response:

{
    "activities" : [
        {
            "id": 69,
            "acted_on_type": "person",
            "acted_on_text": "api_created_first api_created_last",
            "actor_type": "person",
            "actor_company_id": null,
            "actor_machine_id": null,
            "actor_person_id": 2,
            "actor_text": "Michel Jansen",
            "data_text": null,
            "created": "2012-10-17T16:23:26.598000+00:00",
            "acted_on_machine_id": null,
            "acted_on_company_id": 2,
            "acted_on_person_id": 20,
            "acted_on_root_id": null,
            "num_alerts": 0,
            "action_text": "removed account" 
        },
        ....
    ],
    "total_activities": 25,
    "total_pages": 3,
    "page": 1
}

/activity// - retrieves the activity with specified id
sample response:

{
    "id": 3,
    "actor_type": null,
    "actor_text": "System",
    "actor_company_id": null,
    "actor_machine_id": null,
    "actor_person_id": null,
    "action_text": null,
    "acted_on_type": "site",
    "acted_on_text": "All Organizations",
    "acted_on_company_id": 1,
    "acted_on_machine_id": null,
    "acted_on_person_id": null,
    "data_text": "C:/vBoxxCloudDBStore",
    "activity_type_id": 22,
    "created": "2012-10-04T22:40:37.182000+00:00",
    "acted_on_root_id": null
}

/activity/create/- creates an activity with the following parameters

Name	Required	Info
activity_type_id	yes	activity type id
actor_id	yes	id of the actor, interpreted according the to actor_type param
actor_type	yes	type of actor, currently must be one of 'person', 'site', 'machine'
acted_on_id	yes	id of the acted-upon entity, interpreted according to the acted_on_type param
acted_on_type	yes	type of acted-upon entity, currently must be one of 'person', 'site', 'machine', 'root'
actor_text	no	optional additional text
acted_on_text	no	optional additional text
data_text	no	optional additional text

sample response:

{
    "code": "success",
    "id": 34,
    "uri": "/1/management/activity/34/" 
}

Policy

/policy// - retrieves the policy specified by id, currently is a company_id but will most likely change in the future
sample response:

{
    "space_quota": 1073741824,
    "max_file_size": "300",
    "purge_deleted": false,
    "trim_revisions": false,
    "excluded_extensions": ".$$,.$db,.113,.3g2,.3gp,...." 
    "company_id": 2,
    "purge_deleted_frequency": "",
    "user_trim_revisions": false,
    "user_create_backups": false,
    "id": 2,
    "trim_revisions_x": "" 
}

/policy/update/- update a policy with the supplied parameters:

Name	Required	*Info
id	yes	id of the policy to update currently this corresponds directly with a company id
space_quota	no	must be an integer
max_file_size	no	must be an integer
purge_deleted	no	must be either 'true' or 'false' if provided
trim_revisions	no	must be either 'true' or 'false' if provided
excluded_extensions	no	comma-separated list of file extensions, ex: ".mp3,.ogg,*.avi"
user_purge_deleted	no	must be either 'true' or 'false' if provided
purge_deleted_frequency	no	integer deletion purge frequency
user_trim_revisions	no	must be either 'true' or 'false' if provided
user_create_backups	no	must be either 'true' or 'false' if provided
trim_revisions_x	no	integer trim revision cutoff

Root

/root// - retrieves the root specified by id
sample response:

{
    "id": 1,
    "name": "Files",
    "description": "",
    "company_id": 2,
    "person_id": 1,
    "dept_share": false,
    "backup": false
}

/root/create/- creates a new root with the supplied parameters:

Name	Required	Info
company_id	yes	company id for the new root
name	yes	name for the new root
person_id	no	optional person id for the root
default	no	true or false to set the new root to the default for the specified person
description	no	optional description for the new root
dept_share	no	true or false to set the new root as a Team Share

/root/update/- update a root with the supplied parameters:

Name	Required	Info
id	yes	id of the root to be updated
company_id	no	company id for the root
name	no	name for the root
description	no	description for the root
person_id	no	person who will own the root
default	no	true or false to set the root as the person's default root

Implemented Endpoints

/machine// - retrieves the machine specified by id
sample response:

don't have any machines locally for testing...

/machine/update/- update a machine with the supplied parameters:

Name	Required	Info
id	yes	id of the machine to update
bandwidth_throttle	no	integer specifying the bandwidth throttle
throttle_exception_dow	no	must be a parseable list of integers representing days of the week, with 0=Monday, 6=Sunday. example: [0,1,2,3]
throttle_exception_days	no	if provided, must be either 'weekdays' or 'weekends' which will set throttle_exception_dow to [0,1,2,3,4] or [5,6] respectively, and will override any value sent for throttle_exception_dow
throttle_exception_start	no	time value of the form 'HH:mm' or 'HH:mm:ss'
throttle_exception_end	no	time value of the form 'HH:mm' or 'HH:mm:ss'
throttle_exception_throttle	no	integer specifying the throttle exception value

Organizations

/organization// - retrieves the organization specified by id
sample response:

{
    "id": 2,
    "parent_id": 1,
    "name": "Default Organization",
    "slug": "default-organization",
    "description": "",
    "email": "Karel.deGroot@gmail.com",
    "hostname": "localhost",
    "policy": "{ .... }",
    "created": "2012-10-04T16:35:04.701000-06:00",
    "email_server_id": null,
    "psa": null,
    "bandwidth_throttle": null,
    "throttle_exception_days": null,
    "throttle_exception_start": null,
    "throttle_exception_end": null,
    "throttle_exception_throttle": null,
    "throttled": false,
    "active": true,
    "throttle_exception_dow": null
}

/organization//organizations/ - retrieves organizations underneath the organization specified by id. results are returned 10 at a time
/organization//organizations/page// - retrieves page_num page of 10 results
sample response:

{
    "total_pages": 1,
    "page": 1,
    "total_organizations": 3,
    "organizations": [
        {
            "id": 2,
            "parent_id": 1,
            "name": "Default Organization",
            "slug": "default-organization",
            "description": "",
            "email": "Karel.deGroot@gmail.com",
            "hostname": "localhost",
            ....
        },
        {....}
}

/organization//roots/ - retrieves roots underneath the organization specified by id
/organization//roots/page// - retrieves page_num page of 10 results
sample response:

{
    "total_roots": 16,
    "total_pages": 2,
    "page": 1,
    "roots": [
        {
            "company_id": 2,
            "company_name": "Default Organization",
            "root_id": 16,
            "name": "api_updated",
            "physical_space": 0,
            "file_count": 0,
            "revision_count": 0,
            "created": "2012-10-18T15:38:24.293000-06:00",
            "dept_share": false,
            "backup": false,
            "person_id": null,
            "first_name": null,
            "last_name": null,
            "username": null,
            "email": null
        },
        { .... }
    ]
}

/organization//machines/ - retrieves machines underneath the organization specified by id
/organization//machines/page// - retrieves page_num page of 10 results
sample response: don't have any machines to test with locally

/organization//persons/ - retrieves persons underneath the organization specified by id
/organization//persons/page// - retrieves page_num page of 10 results
sample response:

{
    "total_persons": 30,
    "total_pages": 3,
    "page": 1,
    "persons": [
        {
            "id": 31,
            "first_name": "Louis",
            "last_name": "API",
            "email": "titaniumlou+louisapi2@gmail.com",
            "use_ldap": false,
            "username": "" 
        },
        { .... }
    ]
}

/organization/create/- creates an organization with the following parameters:

Name	Required	Info
name	yes	name for the new organization
hostname	no	defaults to an empty string
description	no	defaults to an empty string
contact_email	yes	contact email address for the organization
slug	yes	slug for the organization
policy	yes	policy for the organization
parent_id	yes	id of the parent organization
bandwidth_throttle	no	integer specifying the bandwidth throttle
throttle_exception_dow	no	must be a parseable list of integers representing days of the week, with 0=Monday, 6=Sunday. example: [0,1,2,3]
throttle_exception_days	no	if provided, must be either 'weekdays' or 'weekends' which will set throttle_exception_dow to [0,1,2,3,4] or [5,6] respectively, and will override any value sent for throttle_exception_dow
throttle_exception_start	no	time value of the form 'HH:mm' or 'HH:mm:ss'
throttle_exception_end	no	time value of the form 'HH:mm' or 'HH:mm:ss'
throttle_exception_throttle	no	integer specifying the throttle exception value

/organization/update/- updates an organization with the following parameters:

Name	Required	Info
id	yes	id of the organization to update
name	no	new name for the organization, must be unique in the system
description	no	new description for the organization
contact_email	no	new email for the organization
slug	no	new slug for the organization, must be unique in the system
policy	no	new policy for the organization

Share link functionality:

• Basic share URL: https:///1/sharelink/1/<folder name>/?&session_token=

• Parameters:

o download_notify = 0 or 1 --> defines whether to notify the share creator when the shared file is downloaded: 1 notifies, 0 does not; default is 0

o download_limit = --> defines the number of times a file can be downloaded: default is unlimited

o subscribers = comma separated list of email addresses --> defines the share recipient list where read-only access is provided: default is none

o expires = date in format of YYYY-MM-DD --> defines the expiration date for the share link: default is none

Fully-defined URL example:

http://localhost/1/sharelink/1/folderName/documentName.txt?download_notify=1&download_limit=5&subscribers=Karel.deGroot@gmail.com,christan@gmail.com,joris@gmail.com&download_limit=2&expires=2013-11-01&session_token=5a5aHqVz2AkiLTBF9whrAw7wwKIjPUHRwOXPbpxvpmZaINyrjcaU2NDBUjsFSuEo7MvENkJyh6Ajvgh95tyNtpqo5l98kJG0m7Ddlxv24AWRJWV7sJ3OlfACpD8hIze4

How to Subscribe a User to a Team Share via the API:

Full URL: https://mysite.com/1/management/root/subscribe/?session_token=some_token

This is a POST request that takes the following form variables:

• root_id of the Team Share

• person_id of the user being subscribed

Note: This command will only execute a Web subscription to the Team Share and that machine subscriptions are not supported at this time.