Whitelabel Billing API
This page describes an API that Whitelabel partners can use to control billing and account information for their customers. The API uses the JSON encoding for requests and responses.
Plan list
Plans are identified by an integer
plan_id. Access to certain plans requires the use of a "promo code". To list available plans, use the
/plans/resource:
GET /<api_root>/plans/?promo=<promo_code> HTTP/1.1
HTTP/1.1 200 OK
Date: Mon, 29 Nov 2010 18:16:10 GMT
[
{
"plan_id": 1,
"name": "2 Gigs free",
"plan_duration": "1 month",
"plan_cost": 0,
"storage_gigs": 2
},
....
]
The
?promo=query string part is optional, and if omitted, only public plans will be returned.
Requesting a specific plan (by appending its
plan_idto the list URL) returns only the details for that plan:
GET /<api_root>/plans/1 HTTP/1.1
HTTP/1.1 200 OK
Date: Mon, 29 Nov 2010 18:16:10 GMT
{
"plan_id": 1,
"name": "2 Gigs free",
"plan_duration": "1 month",
"plan_cost": 0,
"storage_gigs": 2
}
User list
GET /<api_root>/users/ HTTP/1.1
HTTP/1.1 200 OK
Date: Mon, 29 Nov 2010 18:16:10 GMT
[
{
"avatar_id": 1001,
"username": "spideroak_user",
"firstname": "Joe",
"lastname": "Smith",
"email": "joe.smith@spideroak.com",
"share_id": "joepublic",
"plan_id": 1,
"bytes_stored": 14245,
"enabled": true
},
....
]
As with plans, you can retrieve details on a specific user by appending the
avatar_idto the list URL (eg.
GET /<api_root>/users/1001).
User details
You can retrieve a user's details by their avatar id, username, e-mail address, or share id by using the
/users/<avatar_id>,
/users/byusername/<username>,
/users/byemail/<email>, or
/users/byshareid/<share_id>resources, respectively.
GET /<api_root>/users/1001 HTTP/1.1
HTTP/1.1 200 OK
Date: Mon, 29 Nov 2010 18:16:10 GMT
{
"avatar_id": 1001,
"username": "spideroak_user",
"firstname": "Joe",
"lastname": "Smith",
"email": "joe.smith@spideroak.com",
"share_id": "joepublic",
"plan_id": 1,
"bytes_stored": 14245,
"enabled": true
}
GET /<api_root>/users/byemail/joe.smith%40spideroak.com HTTP/1.1
HTTP/1.1 200 OK
Date: Mon, 29 Nov 2010 18:16:10 GMT
{
"avatar_id": 1001,
"username": "spideroak_user",
"firstname": "Joe",
"lastname": "Smith",
"email": "joe.smith@spideroak.com",
"share_id": "joepublic",
"plan_id": 1,
"bytes_stored": 14245,
"enabled": true
}
For any user detail URL, you may optionally append a
?device_list=yesquery string to include a list of the user's devices in the output:
GET /<api_root>/users/byusername/spideroak_user?device_list=yes HTTP/1.1
HTTP/1.1 200 OK
Date: Mon, 29 Nov 2010 18:16:10 GMT
{
"avatar_id": 1001,
"username": "spideroak_user",
"firstname": "Joe",
"lastname": "Smith",
"email": "joe.smith@spideroak.com",
"share_id": "joepublic",
"plan_id": 1,
"bytes_stored": 14245,
"enabled": true,
"device_list": [
{
"device_id": 1,
"name": "Joe's PC",
"created": 1190914501,
"last_login": 1292887288,
"last_commit": 1292887322,
"revision": 9738,
"purged": false,
"purge_time": null, // or a timestamp, if purged
},
...
]
}
Additionally, you may optionally append a
?service_access_restrictions=yesquery string to include a list of ip address/service restrictions for the given user:
GET /<api_root>/users/byusername/spideroak_user?service_access_restrictions=yes HTTP/1.1
HTTP/1.1 200 OK
Date: Mon, 29 Nov 2010 18:16:10 GMT
{
"avatar_id": 1001,
"username": "spideroak_user",
"firstname": "Joe",
"lastname": "Smith",
"email": "joe.smith@spideroak.com",
"share_id": "joepublic",
"plan_id": 1,
"bytes_stored": 14245,
"enabled": true,
"service_access_restrictions": [
{
"id": 123,
"service_name": "web_share",
"source_ip_allow": "192.168.1.123",
"start_time": "2011-10-15 14:00:00",
"end_time": null
},
...
]
}
GET /<api_root>/users/byemail/joe.smith%40spideroak.com HTTP/1.1
HTTP/1.1 200 OK
Date: Mon, 29 Nov 2010 18:16:10 GMT
{
"avatar_id": 1001,
"username": "spideroak_user",
"firstname": "Joe",
"lastname": "Smith",
"email": "joe.smith@spideroak.com",
"share_id": "joepublic",
"plan_id": 1,
"bytes_stored": 14245,
"enabled": true
}
User actions
You can perform actions on a user by sending a
POSTrequest to that user's specific URL (by avatar id, username, e-mail address or share id) with a JSON-encoded action object. The response to these messages will be a result object, similar to below:
HTTP/1.1 200 OK
Date: Mon, 29 Nov 2010 18:16:10 GMT
{
"success": true
}
or, on failure:
HTTP/1.1 200 OK
Date: Mon, 29 Nov 2010 18:16:10 GMT
{
"success": false,
"reason": "a message describing the error"
}
Set plan
To set a user's plan, use the
set_planaction. If the plan requires a promo code, include the
codeparameter (otherwise you may omit it):
POST /<api_root>/users/1001 HTTP/1.1
Host: <api_host>
{
"action": "set_plan",
"plan_id": 1,
"code": "promo_code"
}
Set bonus gigs
To grant a user bonus storage gigs, use the
set_storage_gigs
action. You may grant a user up to 50GB of extra space without having to change their plan. If a user is billed directly, this will not affect their plan cost. It is useful for things like rewards for referrals, etc.
To remove a user's storage bonus, set it to 0.
POST /<api_root>/users/1001 HTTP/1.1
Host: <api_host>
{
"action": "set_bonus_gigs",
"bonus_gigs": 1
}
To grant storage space in less than 1GB increments, you may pass a decimal number as a string. For example, to grant 250MB, you would pass the string
"0.25"through the
bonus_gigsparameter.
Disable/enable user
You can disable a user (eg. for non-payment) without removing that user's data from SpiderOak, allowing you to re-enable the user at a later time:
POST /<api_root>/users/1001 HTTP/1.1
Host: <api_host>
{
"action": "set_enabled",
"enabled": false
}
A later request for that user's details will reflect the status:
GET /<api_root>/users/1001 HTTP/1.1
HTTP/1.1 200 OK
Date: Mon, 29 Nov 2010 18:16:10 GMT
{
"avatar_id": 1001,
"username": "spideroak_user",
"firstname": "Joe",
"lastname": "Smith",
"email": "joe.smith@spideroak.com",
"share_id": "joepublic",
"plan_id": 1,
"bytes_stored": 14245,
"enabled": false
}
You can later re-enable a user (eg. if they pay their past-due amount):
POST /<api_root>/users/1001 HTTP/1.1
Host: <api_host>
{
"action": "set_enabled",
"enabled": true
}
Purging users
To remove a user's data from SpiderOak (eg. if they're long overdue on their payments or wish to cancel their account):
POST /<api_root>/users/1001 HTTP/1.1
Host: <api_host>
{
"action": "purge_account"
}
Set email
To set a user's e-mail address on file:
POST /<api_root>/users/1001 HTTP/1.1
Host: <api_host>
{
"action": "set_email",
"email": "my_new_email@spideroak.com"
}
Set access restrictions
To restrict a user's access to certain features by IP address, use the
add_service_access_restrictionaction.
POST /<api_root>/users/1001 HTTP/1.1
Host: <api_host>
{
"action": "add_service_access_restriction",
"service_name": "web_share",
"source_ip_allow": "192.168.1.123",
"start_time": "2011-10-15 14:00:00",
"end_time": null
}
Valid
service_namevalues are
"storagedaemon", "fetchdaemon", "web_share",and
"web_storage".
The
start_timeand
end_timefields may be omitted or
nullif desired.
Clear access restrictions
To remove a service access restriction previously added by the
add_service_access_restrictionaction, use
clear_service_access_restrictions. You must use the
idfield from the list output using
?service_access_restrictions=yeson the user's detail resource.
POST /<api_root>/users/1001 HTTP/1.1
Host: <api_host>
{
"action": "clear_service_access_restrictions",
"restriction_ids": [123, 124, ...] // numeric id from ?service_access_restrictions=yes output
}
Ping
To facilitate remote monitoring of the API, there is a no-op method at
<api_root>/pingthat will respond to GET or POST.
POST /<api_root>/ping HTTP/1.1
HTTP/1.1 200 OK
Date: Mon, 29 Nov 2010 18:16:10 GMT
{
"success": true
}