REST API: Introduction & Authentication

Rest API Introduction

Note: We also have a Javascript API, which you can find information about here.

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

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


Using the API Key

To use the REST API with the REST API Key, you first need to enable it on the Site tab. When you do, it will display the 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. 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 https://.

The extension of the request will determine the response. So a request ending in .json will send back 'application/json' and .xml will return 'application/xml'

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

curl -u EB4585AD9FE0426781ED7C49252F8225:x

User Sessions

You can also authenticate to the REST API using a user session. The session is created with the user's username and password. If the user is a Site Admin, the session will have full access to the entire API. Sessions created from regular user accounts will only be able to access files that user can access, and no access will be granted to site administration functions in the API.

To create a session, a POST request is made to with the user's username and password as per this example:

POST /sessions.(json|xml)

Sample Request:

    "username": "motor",
    "password": "vroom"
<?xml version="1.0" encoding="UTF-8"?>

Sample Response:

    "id": "8c2e9f493dd8a857d5cdddbb7bf64ece0b7fb599"
<?xml version="1.0" encoding="UTF-8"?>

Once a session has been created, you authenticate to the REST API by sending a cookie called BrickAPI set to the value of the session ID. Here is an example using Curl:

curl -b BrickAPI=8c2e9f493dd8a857d5cdddbb7bf64ece0b7fb599

Logging Out a User Session

User sessions can be ended by using a DELETE call to If a valid user session is passed in by cookie, then that user session will be deleted. It is similar to the user logging out. Note that calling DELETE at always results in a response of an empty array, even if an invalid user session was passed in.

<?xml version="1.0" encoding="UTF-8"?>
<nil-classes type="array"/>

More REST API Resources


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.

SSL Certificate
Security Seals
credit card logos