API: Users¶

Make sure to read the API Overview before reading this document.

Retrieving a List of Users¶

Required Variables¶

Variable	Description
section	Must be set to `users`.
action	Must be set to `retrieve`.
api_key	Must be set to your unique API key.

Optional Variables¶

Variable	Description
user_id	An integer or set of integers specifying the user IDs you would like us to list. You can specify a single integer or a comma-separated list of integers (Examples: `1005` or `1005, 1010, 1254`). You can also use the keyword `all` to include all users. This parameter is set to `all` by default.

Response¶

After we receive these variables, we will respond with raw XML containing status and user information, including authorized services for each user.

Example:

<?xml version="1.0" encoding="UTF-8"?>
<xml>
    <status>1</status>
    <user id="73">
        <username>John</username>
        <service id="1234"/>
        <service id="1235"/>
        <service id="1236"/>
        <limit>10</limit>
        <created>2009-11-30 11:28:20</created>
    </user>
</xml>

Creating a User¶

Required Variables¶

Variable	Description
section	Must be set to `users`.
action	Must be set to `create`.
api_key	Must be set to your unique API key.
username	A string that specifies the identifying name of the new user. Note: If the 'username' is an email address, the 'password' variable is ignored because the user will be required to set their own password.
password	(Conditionally Required) A string that specifies the password for the new user. Note: If the username is not an email address, the 'password' variable is required.

Optional Variables¶

Variable	Description
limit	An integer which specifies the maximum number of devices the user can activate during a billing period. A new user can activate an unlimited number of devices by default.

Response¶

If a new user is successfully created after receiving your request, we will respond with raw XML containing a status of 1 and the new user's ID. Additionally, if the username is an email address, an invitation email will be sent to the user. The user will only be able to log in and use the system after accepting the invitation.

Example:

<?xml version="1.0" encoding="UTF-8"?>
<xml>
    <status>1</status>
    <id>1001</id>
</xml>

Editing a User¶

Variables omitted when editing a user will not affect the variable's correspondent user settings.

Required Variables¶

Variable	Description
section	Must be set to `users`.
action	Must be set to `update`.
api_key	Must be set to your unique API key.
user_id	An integer which specifies the user ID you wish to edit.

Optional Variables¶

Variable	Description
username	A string which specifies what you'd like to rename the user. We will return an error code if the new username already exists in the system.
password	A string which specifies the new password for the user.
limit	An integer which specifies the maximum number of devices the user can activate during a billing period. A new user can activate an unlimited number of devices by default.

Response¶

If the user you specified is successfully edited after we receive these variables, we will respond with raw XML containing a status of 1.

Example:

<?xml version="1.0" encoding="UTF-8"?>
<xml>
    <status>1</status>
</xml>

Deleting a User¶

Required Variables¶

Variable	Description
section	Must be set to `users`.
action	Must be set to `delete`.
api_key	Must be set to your unique API key.
user_id	An integer or set of integers which specify the user IDs you wish to delete. You can specify a single integer or a comma-separated list of integers (Examples: `1005` or `1005, 1010, 1254`). You can also use the keyword `all` to delete all users.

Response¶

If the users you specified are successfully deleted after we receive these variables, we will respond with raw XML containing a status of 1.

Example:

<?xml version="1.0" encoding="UTF-8"?>
<xml>
    <status>1</status>
</xml>

Validating a User¶

Required Variables¶

Variable	Description
section	Must be set to `users`.
action	Must be set to `validate`.
api_key	Must be set to your unique API key.
username	A string which specifies the username of the user to validate
password	A string which specifies the password of the user to validate.

Response¶

After we receive these variables and if credentials are valid, we will respond with raw XML containing status and user information, including authorized services the user.

Example:

<?xml version="1.0" encoding="UTF-8"?>
<xml>
    <status>1</status>
    <user id="73">
        <username>John</username>
        <service id="1234"/>
        <service id="1235"/>
        <service id="1236"/>
        <limit>10</limit>
        <created>2009-11-30 11:28:20</created>
    </user>
</xml>