User Accounts

Creating Accounts

POST /users/

Create a user with the given information.

JSON Parameters:  

• username (string) – The username for the new user.
• name (string) – The new user’s full name.
• email (string) – The new user’s email address.
• password_bcrypt (string) – Optional. A bcrypt hash of the user’s desired password. If omitted, a temporary password will be generated and returned in the temp_password field of the response.
• promo (string) – Optional. The promo code to apply to the account during signup.

The following optional additional parameters are available to authenticated enterprise partners:

JSON Parameters:  

• group_id (int) – Id of the enterprise group the new user is to be part of.
• plan_id (int) – The plan to assign to the user, if different from the default group plan.
• bonus_bytes (int) – Bonus storage to grant to the user above their plan limit.

Note

Authenticated enterprise partners may omit the username parameter, in which case an automatically incrementing numbered username will be generated and used. This is useful when users are identified by email address rather than username. The generated username will be returned in the username field of the response.

Status Codes:

• 200 – User was created successfully (see Example Success Response).
• 400 – Invalid or missing request parameters.
• 402 – (Partners only) Not enough storage space available to accommodate new user.
• 409 – Username or email address conflict with an existing account (see Example Conflict Response). Also returned when specified group_id or plan_id are invalid.

Example Success Response:

HTTP/1.1 200 OK
Content-type: text/javascript

{
    "username": "user_auto_12345",      // example auto-generated username
    "temp_password": "1234-12345-1234"  // if password was omitted
}

Example Conflict Response:

HTTP/1.1 409 Conflict
Content-type: text/javascript

{
    "reason": "The following fields conflict with an existing account",
    "conflicts": ["username", "email"]
}

Listing Accounts (authenticated)

GET /users/

List existing users. This method is only available to partners, while authenticated.

Query Parameters:  

• group_id – Optional. Limit results to users within specified group.
• plan_id – Optional. Limit results to users assigned to plan.
• search – Optional. Limit results to users whose name or email address contains this text.
• limit (int) – The maximum number of results to return
• offset (int) – The number of rows to skip before beginning to return rows.
• order_by (string) – A comma separated list of fields to order by. All of the JSON Parameters below are valid fields to order by.
• search_by (string) – A comma separated list of fields to search on. The syntax is field_name separator value. If there’s a comma within a value replace it with , Example email=test,@test,bytes_stored>0

Search by

Field name	Separators	Value
username	=	string
name	=	string
email	=	string
share_id	=	string
creation_time	>, >=, =, <=, <	integer
last_login	>, >=, =, <=, <	integer
num_devices	>, >=, =, <=, <	integer
bytes_stored	>, >=, =, <=, <	integer
storage_bytes	>, >=, =, <=, <	integer
bonus_bytes	>, >=, =, <=, <	integer
plan_id	>, >=, =, <=, <	integer
group_id	>, >=, =, <=, <	integer
group_id	>, >=, =, <=, <	integer
enabled	=	1 for True 0 for False
purgehold_active	=	1 for True 0 for False
recently_stopped_uploading	=	Two integers separated by a |. Example 2592000|1209600. This searches for users who have uploaded within the past 2592000 seconds, but have not uploaded within the past 1209600 seconds.

Status Codes:

• 400 – One or more of the parameters is invalid.

Returns a JSON list of objects containing the same information as Viewing Account Info (authenticated), below.

Viewing Account Info (authenticated)

GET /users/(username|email)

View user information. This method is only available to partners, while authenticated.

Status Codes:

• 200 – See JSON Parameters returned in the response below.
• 404 – A user with the specified username or email address could not be found.

Returns the following information in successful response:

JSON Parameters:  

• username (string) – The user’s username.
• name (string) – The user’s full name.
• email (string) – The user’s email address.
• share_id (string) – The user’s ShareID.
• promo (string) – The promo code used during account signup.
• creation_time (int) – Time at which the user signed up (UNIX timestamp, GMT).
• last_login (int) – Time at which the user last logged in (UNIX timestamp, GMT).
• bytes_stored (int) – Amount of storage space the user is currently using, in bytes.
• storage_bytes (int) – Amount of storage space available on the user’s plan, in bytes.
• bonus_bytes (int) – Amount of bonus storage space on top of the user’s plan, in bytes.
• plan_id (int) – The plan assigned to the user.
• group_id (int) – The group assigned to the user (enterprise users only).
• enabled (bool) – True if the user is enabled.
• share_rooms (list) – A list of RoomKeys identifying the user’s ShareRooms.
• purgehold_active (bool) – True if a purge hold is in force for this account. That is, purging of user’s deleted blocks is currently inhibited, due to either an individual account (purgehold_start_time and purgehold_end_time) or an enterprise-wide purge hold.
• purgehold_start_time (int) – Account-specific beginning time (UNIX timestamp, GMT) of interval during which purging of user’s deleted blocks is inhibited. The interval lasts until purgehold_end_time, or forever if purgehold_end_time is 0.
• purgehold_end_time (int) – End time (UNIX timestamp, GMT) of interval, starting at purgehold_start_time, during which purging of user’s deleted blocks is inhibited. If purgehold_end_time is 0 then purging is inhibited any time after purgehold_start_time, if set.

Viewing Account Devices (authenticated)

GET /users/(username|email)/devices

View device information. This method is only available to partners, while authenticated.

Status Codes:

• 200 – See JSON Parameters returned in the response below.
• 404 – A user with the specified username or email address could not be found.

Returns a JSON list with the following information for each device in successful response:

JSON Parameters:  

• device_id (int) – The device id.
• name (string) – The device name.
• creation_time (int) – Time at which the device was created (UNIX timestamp, GMT).
• reinstalled (int) – Time at which the device was last reinstalled (UNIX timestamp, GMT).
• last_login (int) – Time at which the user last logged into this device (UNIX timestamp, GMT).
• last_backup_complete (int) – Time at which the device last completed a backup (UNIX timestamp, GMT).

Viewing Account Shares (authenticated)

GET /users/(username|email)/shares/

List RoomKeys for user’s ShareRooms. This method is only available to partners, while authenticated.

Status Codes:

• 200 – Returns a JSON list of RoomKeys.
• 404 – A user with the specified username or email address could not be found.

Viewing Account Share Details (authenticated)

GET /users/(username|email)/shares/(roomkey)

Return detailed information about the named ShareRoom. This method is only available to partners, while authenticated.

Status Codes:

• 200 – See JSON Parameters returned in the response below.
• 404 – A user with the specified username or email address could not be found.

Returns a JSON object corresponding to the named share with the following fields in a successful response:

JSON Parameters:  

• room_key (string) – The RoomKey corresponding to this share.
• name (string) – The share name.
• description (string) – The share description.
• password_required (bool) – Whether the ShareRoom requires a password to be accessed via the web.
• paths (list) – A list of paths contained in the share. Each item is a JSON list containing two items: 1. the device_id containing the shared folder, 2. the filesystem path of the shared folder.
• creation_time (int) – Time at which the share was created (UNIX timestamp, GMT).
• update_time (int) – Time at which the share was last updated (UNIX timestamp, GMT).

Viewing Account Extra Info (authenticated)

GET /users/(username|email)/extra

View extra info associated with this account. This method is only available to partners, while authenticated.

Status Codes:

• 200 – Associated JSON data is returned. Will return an empty document if no data is associated with this account.
• 404 – A user with the specified username or email address could not be found.

Modifying Account Extra Info (authenticated)

POST /users/(username|email)/extra

Associate an arbitrary JSON object with the account. This method is only available to partners, while authenticated.

Status Codes:

• 204 – The JSON object was updated successfully.
• 404 – A user with the specified username or email address could not be found.

Modifying Accounts (authenticated)

POST /users/(username|email)

Modify user information. This method is only available to partners, while authenticated.

The following parameters are modifyable. You may include any number of the parameters below in the request.

JSON Parameters:  

• name (string) – The user’s full name.
• email (string) – The user’s email address.
• plan_id (int) – The plan assigned to the user.
• group_id (int) – The group assigned to the user (enterprise users only).
• bonus_bytes (int) – Bonus storage to grant to the user above their plan limit.
• enabled (bool) – True if the user is enabled.
• purgehold_active (bool) – True to enable purge hold for this account. While enabled, user’s deleted blocks and not purged.

The following response codes are possible:

Status Codes:

• 200 – User was modified successfully.
• 400 – Invalid request parameters were included.
• 402 – Attempted to set plan_id or group_id parameter that would cause space allocation to go beyond the available amount.
• 404 – A user with the specified username or email address could not be found.
• 409 – Email address conflicts with another existing account, or an invalid group_id or plan_id were specified.

Deleting Accounts (authenticated)

DELETE /users/(username|email)

POST /users/(username|email)?action=delete

Delete the specified user. This method is only available to partners, while authenticated.

This action is available using either the HTTP DELETE method, or POST with the ?action=delete query parameter.

Status Codes:

• 200 – User was deleted successfully.
• 404 – A user with the specified username or email address could not be found.

Sending Account Activation Emails (authenticated)

POST /users/(username|email)?action=sendactivationemail

Send the specified user an activation email. This method is only available to partners, while authenticated. Additionally, the user must not have set up any devices yet, as the account password will be set to a temporary activation code which will be sent in the email.

Status Codes:

• 200 – The email was sent successfully.
• 404 – A user with the specified username or email address could not be found.
• 409 – The user has already set up a device, so an activation email was not sent.