BrickFTP™

Our REST API is meant for people who require the highest level of integration between BrickFTP and your own application, website, or database.

The REST API uses plain XML over HTTP. Resources (such as Users or Groups) are manipulated individually using the 4 HTTP verbs (GET/POST/PUT/DELETE).

Authentication

To use the REST API, you first need to enable it on the Site tab. When you do, it will display a REST API Key. This API Key must be provided in every API request. Note that this is different from the Javascript API Key. The REST API Key must be kept secure, as it allows full access to your site account via the API. If you feel that your API Key is compromised, please contact us immediately to disable it!

The REST API uses HTTP Basic Authentication to collect the API Key. You should pass in the API Key as the Username field in HTTP Basic Authentication. The password field may be left blank, or you may use a dummy value, such as x.

https://app.brickftp.com/ is the base URL for all API requests. Do not use a custom subdomain or domain name, even if one is configured for your account. Also, be sure that you are connecting via SSL (https://).

Here's an example of authenticating the the API using cURL, assuming EB4585AD9FE0426781ED7C49252F8225 is your API key:

curl -u EB4585AD9FE0426781ED7C49252F8225:x https://app.brickftp.com/users.xml

General API Operations

To read an object or list of objects, send a GET request. Each type of object (User, Group, etc.) has a URL that can be used for listing. Further, each object has its own URL that will allow you to retrieve all the information available about that object. Our response will be an XML document containing the object or the collection of objects.

To create or update an object, send a POST or PUT request, respectively. With these requests, you'll need to include an XML document containing the data to create or update as the raw post data. You will also need to set the "Content-type: application/xml" header. Here's a quick example of POST and PUT:

curl -u EB4585AD9FE0426781ED7C49252F8225:x -H 'Content-Type: application/xml' \
  -d '<user><username>alice</username><password>abc123</password></user>' \ 
  https://app.brickftp.com/users.xml

curl -u EB4585AD9FE0426781ED7C49252F8225:x -X PUT -H 'Content-Type: application/xml' \
  -d '<password>abc123</password></user>' https://app.brickftp.com/users/123.xml

If successful, we will send the 201 Created (new objects) or 200 Success (existing objects) header. We will also send an XML representation of the full object in the body of the response. In the event of a failure (username already taken, password not provided, etc.) we will send a 422 Unprocessable Entity Header and put an XML representation of the errors in the body of the response.

To delete an object, send a DELETE request. It is not necessary to include a request body. We will respond with a 200 Success header.

curl -u EB4585AD9FE0426781ED7C49252F8225:x -X DELETE https://app.brickftp.com/users/123.xml

Users

Here are the operations for listing, showing, creating, updating, and deleting users. After each operation is either a sample request or sample response. An explanation of all the properties follows the operations.

List

<users>
 <user>
  <id type='integer'>7</id>
  <username>johndoe</username>
  <name>John Doe</name>
  <email>john@doe.com</email>
  <notes>CTO</notes>
  <group_ids>3,4</group_ids>
  <ftp_permission type='trueclass'>true</ftp_permission>
  <web_permission type='trueclass'>true</web_permission>
  <attachments_permission type='trueclass'>false</attachments_permission>
  <self_managed type='trueclass'>true</self_managed>
  <require_password_change type='trueclass'>false</require_password_change>
  <allowed_ips></allowed_ips>
  <user_root></user_root>
 </user>
 <user>
  <id type='integer'>8</id>
  <username>janedoe</username>
  <name>Jane Doe</name>
  <email>jane@doe.com</email>
  <notes>COO</notes>
  <group_ids>4</group_ids>
  <ftp_permission type='trueclass'>true</ftp_permission>
  <web_permission type='trueclass'>true</web_permission>
  <attachments_permission type='trueclass'>false</attachments_permission>
  <self_managed type='trueclass'>true</self_managed>
  <require_password_change type='trueclass'>false</require_password_change>
  <allowed_ips></allowed_ips>
  <user_root>Operations/</user_root>
 </user>
</users>

Show

<user>
 <id type='integer'>7</id>
 <username>johndoe</username>
 <name>John Doe</name>
 <email>kevin@actionverb.com</email>
 <notes>CTO</notes>
 <group_ids>3,4</group_ids>
 <ftp_permission type='trueclass'>true</ftp_permission>
 <web_permission type='trueclass'>true</web_permission>
 <attachments_permission type='trueclass'>false</attachments_permission>
 <self_managed type='trueclass'>true</self_managed>
 <require_password_change type='trueclass'>false</require_password_change>
 <allowed_ips></allowed_ips>
 <user_root></user_root>
</user>

Create

<user>
 <username>johndoe</username>
 <password>doejohn123</password>
 <name>John Doe</name>
 <email>john@doe.com</email>
 <notes>CTO</notes>
 <group_ids>3,4</group_ids>
 <ftp_permission>true</ftp_permission>
 <web_permission>true</web_permission>
 <attachments_permission>false</attachments_permission>
 <self_managed>true</self_managed>
 <require_password_change>false</require_password_change>
 <allowed_ips></allowed_ips>
 <user_root></user_root>
 <grant_permission>read</grant_permission>
</user>

Update

<user>
 <password>new_password</password>
 <require_password_change>true</require_password_change>
</user>

Delete

The Delete command neither requires nor returns a request body.

Property Reference

• id - Integer - unique identifier of each User. Each user is given an ID automatically upon creation.
• username - String (50 character limit) - Username for the user. This is how the user will be displayed on the site.
• password - String - Password for the user. This property is set-only. It cannot be retrieved via the API.
• name - String (50 character limit) - Real name of the user. For your reference.
• email - String (50 character limit) - E-Mail address of the user.
• notes - Text - You may use this property to store any additional information you require. There are no restrictions on its formatting.
• group_ids - Comma-Separated List of Integers - IDs of the Groups that this user is in.
• ftp_permission - Boolean (default: true) - Allow user access via FTP/FTPS (port 21 or 990) interface.
• web_permission - Boolean (default: true) - Allow user access via HTTP/HTTPS (port 80 or 443) interface.
• attachments_permission - Boolean (default: false) - Allow user to use Sharing tab in web interface to share files with anonymous users via a unique URL.
• self_managed - Boolean (default: true) - Allow user to change their password and user information via the web interface.
• require_password_change - Boolean (default: false) - Require user to change their password at their next login. Note: requires web_permission to be true, as password changes can only occur via the web interface.
• allowed_ips - Text - List allowed IPs, one per line. You may specify a range in CIDR format, such as 192.168.1.0/27 Leave blank to allow all IPs. If you are also restricting IP addresses on the Site tab, users matching in either place will be allowed to log in.
• user_root - String (250 character limit) - folder to show as the root when this user logs in via the FTP interface. Make sure this folder exists, as it will not be automatically created. Does not apply to the web interface! This should not contain a leading slash, but must contain a trailing slash. Example: Users/jenny/
• grant_permission - Enum (full, read, write) - If provided and set to either full, read, or write, the user will be granted that permission on their FTP root folder as defined by the user_root. This property is set-only. It cannot be retrieved via the API.

Groups

Here are the operations for listing, showing, creating, updating, and deleting groups. After each operation is either a sample request or sample response. An explanation of all the properties follows the operations.

List

<groups>
 <group>
  <id type='integer'>1</id>
  <name>Management</name>
  <notes>Has access to all areas: Ops, HR, and Board</notes>
  <user_ids>1,2</user_ids>
 </group>
 <group>
  <id type='integer'>2</id>
  <name>Operations</name>
  <notes>Has access to Ops folders only.</notes>
  <user_ids>3,4</user_ids>
 </group>
 <group>
  <id type='integer'>3</id>
  <name>HR</name>
  <notes>Has access to HR folders only.</notes>
  <user_ids>5,6,7,8,9,10</user_ids>
 </group>
</groups>

Show

<group>
 <id type='integer'>1</id>
 <name>Management</name>
 <notes></notes>
 <user_ids>1,2</user_ids>
</group>

Create

<group>
 <name>Chicago Office</name>
 <notes>For members of our Chicago Office</notes>
 <user_ids>3,7,9</user_ids>
</group>

Update

<group>
 <notes>Submitting this will change this note, but not the name or group membership.</notes>
</group>

Delete

The Delete command neither requires nor returns a request body.

Property Reference

• id - Integer - unique identifier of each Group. Each group is given an ID automatically upon creation.
• name - String (50 character limit) - name of the Group. This is how the group will be displayed on the site.
• notes - Text - You may use this property to store any additional information you require. There are no restrictions on its formatting.
• user_ids - Comma-Separated List of Integers - IDs of the Users that are in this group.

Questions?

We hope that this document helps you integrate our REST API. If you have any questions, please feel free to contact us.

If you would like a feature added to the API, let us know and we'll let you know whether it's possible.