BlueFolder API 1.0 (Beta)

Overview

The BlueFolder API is an interface that you can use to programmatically interact with your BlueFolder account. The API is implemented using XML over HTTPS.

Prerequisites

The API is available to BlueFolder Premium Edition subscribers only. To use the API, you must first enable API access for your BlueFolder account. To enable your account for API access, go to Settings > API and click the "Enable my BlueFolder account for API access" checkbox.

Additionally, each user account that will interact with the API must also be enabled for API access. To enable a user account for API access, go to Settings > API, and then add the user you want to enable to the Authorized API Users list.

Authentication

All API requests must be made via SSL over HTTPS. Requests are authenticated to the API using Basic HTTP Authentication.

Each BlueFolder user account has a unique API token, which can be found in the "Authorized API Users" table located in "Settings > API". A user's API token is tied to their password - if the password changes, so will the API token. API Tokens should be guarded just as carefully as a password.

Basic HTTP authentication typically requires a "username:password" pair, but the BlueFolder API only requires a single token as the username so you'll only use the "username" field (just use "X" or any string you prefer as the password). To authenticate your API requests, concatenate your API token and a bogus password together with a colon (e.g. "my-api-token:X"), and then Base64 encode that string. Add the "Authorization" HTTP header to your API request, and sets the header's value to the Base64-encoded string you just created.

Requests must be submitted via HTTPS POST in the following format.

<request> request_details </request>

Successful Requests

A successful request to the API will return the following XML:

<response status="ok"> response_content </response>

Failed Requests

A failed request to the API will return the following XML:

<response status="fail"> <error code="error_code"> error_message </error> </response>