Brightbox API Documentation 1.0.0beta

Introduction

Welcome to the Brightbox Cloud API! The API allows you to programmatically control the computing resources available to your account.

It currently allows management of the following resources:

• Servers - virtualised compute instances in a range of capabilities (Server Types)
• Server Groups - collections of Servers
• Load Balancers - for dividing network traffic across multiple Servers
• Cloud IPs - dynamic public IP addresses that can be moved between Servers or Load Balancers
• Database Servers - hosted SQL databases (MySQL or Postgres)
• Database Snapshots - snapshots of Database Servers taken from an SQL Instance
• Firewall Policies - collections of Firewall Rules applied to a Server Group
• Firewall Rules - a rule to apply to network traffic as part of a Firewall Policy
• Images - uploaded disk images or snapshots made from existing services

In addition it allows management of some aspects of your User, Account, Collaborations and API client details.

Requirements to use the service

In order to use the Brightbox Cloud service and the API you must have a valid User profile and an Account which has been successfully verified.

New users can sign up to the service at https://manage.brightbox.com

If you were a user during the beta period of the service, you should have received instructions about how to upgrade your profile and account details to gain full access.

General concepts

Users and Accounts

In the Brightbox Cloud we differentiate between a User, a person who uses the site, and an Account which is where costs and resources are managed.

A User must agree to the terms and conditions to use the service. An Account must be setup with a valid payments card and be verified by telephone.

At the present time we are limiting each User to having one Account. This may change in the future to allow multiple users to manage one Account and a User having several Accounts.

The best way to manage your user and account details are using the management control panel at https://manage.brightbox.com

Regions and Zones

We divide our service into two geographical layers. Regions are larger areas which contain several Zones. Zones are roughly equivalent to data centres. Zones however are completely independent of each other.

The Brightbox API is currently regional. So you can interact with several Zones through the API.

Resource IDs

All resources have a unique and immutable ID. These consist of a three letter code, a dash and approximately five alphanumeric characters. The characters are actually a number encoded as Base36 to save on typing. As such the number range may expand and become longer.

API tools and client libraries

Whilst the Brightbox Cloud API is already pretty simple to use we already provide a number of tools to help. Some of these may help you rather than having to work against the API directly.

Brightbox CLI

We provide a set of command line tools to access and manage most of the resources. Details are available at the documentation site.

The CLI tools are available as either a Ruby gem or a Ubuntu/Debian package.

Fog (Ruby Library)

Fog is a cloud abstraction library for Ruby that standardise some of the details of different cloud providers APIs.

Support for the Cloud API in Fog is officially maintained by Brightbox.

Our CLI tools use Fog.

Apache Libcloud (Python Library)

Libcloud is a standard Python library that abstracts away differences among multiple cloud provider APIs. We added support for our API to libcloud, which is now included upstream.

http://libcloud.apache.org/

Chef/Knife plugin

rubiojr kindly wrote a Knife plugin to allow you to use Chef to provision Brightbox cloud servers in one line.

Blog post covering: Bootstrapping an Ubuntu Image in Brightbox’s Cloud using knife

API concepts

API endpoint URLs

All communication with the API is required to be secured using SSL so the protocol must always be HTTPS.

The API endpoint URL for the GB1 region is: api.gb1.brightbox.com

API versioning

The Brightbox Cloud API uses semantic versioning

The current version of the API is 1.0.0beta but the URL only includes the major and minor parts of the version number

To use a particular version of the API, add it to the base API endpoint URL e.g api.gb1.brightbox.com/1.0/

DateTime and Timezone

All Times are stored and reported in UTC. The ISO8601 format (e.g. 2011-09-13T16:09:54Z) is used throughout the API. The DateTimes are returned as strings since JSON does not have a DateTime object in the specification.

Authentication

Authentication is done using OAuth 2.0 https://tools.ietf.org/html/rfc6749 requesting an access token using either the client_credentials, password, or refresh_token grant types.

Scopes

We offer two OAuth scopes that can be used to restrict the scope of any API client’s operations.

The Brightbox IaaS API described here is covered by the infrastructure scope.

Orbit is covered by the orbit scope.

If a token is issued for orbit it can not be used to access the infrastructure API.

OAuth 2.0 Grant types

We currently allow accessing the API using client credentials (using API clients) or using a user’s own login credentials (using OAuth applications).

Before you can access the Brightbox API you need to have a client identifier and secret for the client you plan to use.

We support two types of client each linked to a different grant type.

Client Credentials using API clients

This is the simple Client Credentials (client_credentials) grant type. API clients can only access the account that they belong to.

API client credentials are an identifier and secret issued to a single account to access the API, commonly used for authenticating automated systems.

To request an access token the Client must send a POST request to https://api.gb1.brightbox.com/token

The request must use Basic HTTP authentication using the client_id as username and client_secret as password.

It must include the following parameters:

Data can be sent with Content-Type of either application/x-www-form-urlencoded or application/json.

Example curl request/response:

$ curl https://api.gb1.brightbox.com/token \
    -X POST \
    -u "cli-entid:secret" \
    -d "grant_type=client_credentials"
{
    "access_token": "414028a4b75139fc1b03b51dc294d1b4c591d666",
    "token_type": "Bearer",
    "scope": "infrastructure, orbit",
    "expires_in": 7200
}

Example JSON request/response:

POST /token HTTP/1.1
Host: api.gb1.brightbox.com
Authorization: Basic Y2xpLWVudGlkOmNsaWVudF9zZWNyZXQ=
Content-Type: application/json

{"grant_type": "client_credentials"}

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
X-Oauth-Scopes: infrastructure, orbit
Content-Length: 131
Date: Fri, 21 Aug 2015 11:05:48 GMT
Connection: Keep-Alive

{
    "access_token": "1c2870d471741bc9c7a1a03ccf7485c2df4f443e",
    "token_type": "Bearer",
    "scope": "infrastructure, orbit",
    "expires_in": 7200
}

See https://tools.ietf.org/html/rfc6749#section-4.4

Resource Owner Password Credentials using OAuth applications

This is OAuth 2‘s Resource Owner Password Credentials (password) grant type. It is a bit harder to work with since it involves credentials for the client and also for the user.

We currently check that the client’s secret is correct which is optional in the OAuth 2.0 spec but all access rights comes from the user’s details.

Since a user can access several accounts, an additional account_id parameter is required for most API calls to specify which is being used. This is not required for requesting a token.

In addition to the access token, users are returned a refresh token. This can be used to request a new access token without reentering your password.

To request an access token the Client must send a POST request to https://api.gb1.brightbox.com/token

The request must use Basic HTTP authentication using the client_id as username and client_secret as password.

It must include the following parameters:

Data can be sent with Content-Type of either application/x-www-form-urlencoded or application/json.

Example curl request/response:

$ curl https://api.gb1.brightbox.com/token \
    -X POST \
    -u "app-entid:secret" \
    -d "grant_type=password" \
    -d "username=bob@example.com" \
    -d "password=bobKNOWSs3cUirty"
{
    "access_token": "5a8fdabb155e1230dffd5a77a11d8885c74d862c",
    "token_type": "Bearer",
    "refresh_token": "6bbd76a3b2d87afe2b13e9bdfaae340e23b4ae26",
    "scope": "infrastructure, orbit",
    "expires_in": 7200
}

Example JSON request/response:

POST /token HTTP/1.1
Host: api.gb1.brightbox.com
Authorization: Basic Y2xpLWVudGlkOmNsaWVudF9zZWNyZXQ=
Content-Type: application/json

{"grant_type":"password"}

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
X-Oauth-Scopes: infrastructure, orbit
Content-Length: 190
Date: Fri, 21 Aug 2015 11:02:41 GMT
Connection: Keep-Alive

{
    "access_token": "0ace2df4de19d42ba7bcae392d0ece2ea6df49a6",
    "token_type": "Bearer",
    "refresh_token": "3f2a04d881c07edc6acc525b16b25de74d75debc",
    "scope": "infrastructure, orbit",
    "expires_in": 7200
}

See https://tools.ietf.org/html/rfc6749#section-4.3

Two Factor Authentication (2FA)

If you have enabled two factor authentication (2FA) you must also include the generated Time-based One Time Password (TOTP) with the token request.

You can do this in two ways. Preferably you can sent the TOTP using the X-BRIGHTBOX-OTP header.

POST /token HTTP/1.1
Host: api.gb1.brightbox.com
Authorization: Basic Y2xpLWVudGlkOmNsaWVudF9zZWNyZXQ=
X-Brightbox-OTP: 123456
Content-Type: application/json

{"grant_type":"password"}

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
X-Oauth-Scopes: infrastructure, orbit
Content-Length: 190
Date: Fri, 21 Aug 2015 11:02:41 GMT
Connection: Keep-Alive

{
    "access_token": "0ace2df4de19d42ba7bcae392d0ece2ea6df49a6",
    "token_type": "Bearer",
    "refresh_token": "3f2a04d881c07edc6acc525b16b25de74d75debc",
    "scope": "infrastructure, orbit",
    "expires_in": 7200
}

Alternatively append the current TOTP to the password separated by a + and send in place of your password. This may need to be URL encoded as %2B depending on how the data is sent.

$ curl https://api.gb1.brightbox.com/token \
    -X POST \
    -u "app-entid:secret" \
    -d "grant_type=password" \
    -d "username=bob@example.com" \
    -d "password=bobKNOWSs3cUirty%2B123456"
{
    "access_token": "5a8fdabb155e1230dffd5a77a11d8885c74d862c",
    "token_type": "Bearer",
    "refresh_token": "6bbd76a3b2d87afe2b13e9bdfaae340e23b4ae26",
    "scope": "infrastructure, orbit",
    "expires_in": 7200
}

Refresh Token Credentials using OAuth applications

Refresh tokens are only granted to users authenticating with passwords. When an access token is given, a refresh token is also given.

You can request a new access token using a valid refresh token to extend access to the API without having to prompt for the password again.

The same client must be used to request an extension. Refresh tokens do expire but have a longer life than access_tokens.

To request an access token the Client must send a POST request to https://api.gb1.brightbox.com/token

The request must use Basic HTTP authentication using the client_id as username and client_secret as password.

It must include the following parameters:

Data can be sent with Content-Type of either application/x-www-form-urlencoded or application/json.

Example curl request/response:

$ curl https://api.gb1.brightbox.com/token \
    -X POST \
    -u "app-entid:secret" \
    -d "grant_type=refresh_token" \
    -d "refresh_token=3f2a04d881c07edc6acc525b16b25de74d75debc"
{
    "access_token": "5a8fdabb155e1230dffd5a77a11d8885c74d862c",
    "token_type": "Bearer",
    "refresh_token": "6bbd76a3b2d87afe2b13e9bdfaae340e23b4ae26",
    "scope": "infrastructure, orbit",
    "expires_in": 7200
}

Example JSON request/response:

POST /token HTTP/1.1
Host: api.gb1.brightbox.com
Authorization: Basic Y2xpLWVudGlkOmNsaWVudF9zZWNyZXQ=
Content-Type: application/json

{"grant_type":"refresh_token","refresh_token":"6bbd76a3b2d87afe2b13e9bdfaae340e23b4ae26"}

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
X-Oauth-Scopes: infrastructure, orbit
Content-Length: 190
Date: Fri, 21 Aug 2015 11:02:41 GMT
Connection: Keep-Alive

{
    "access_token": "0ace2df4de19d42ba7bcae392d0ece2ea6df49a6",
    "token_type": "Bearer",
    "refresh_token": "3f2a04d881c07edc6acc525b16b25de74d75debc",
    "scope": "infrastructure, orbit",
    "expires_in": 7200
}

See https://tools.ietf.org/html/rfc6749#section-6

Responses

A successful request returns a JSON response including:

• access_token the Bearer token used to access the API
• token_type which is always "Bearer"
• refresh_token for users using "password" which can be used to get replacement tokens
• scope the scopes issued to this token
• expires_in the number of seconds the token is valid for (usually 7200 seconds.

Client applications should be designed to handle re-authentication on receipt of a 401 Unauthorised response from the API.

Unsuccessful requests return a 401 Unauthorised response if the credentials are wrong. For any other mistakes such as the wrong grant type it will return a 400 Bad Request.

Making API requests

Requests are made by including the access token in the HTTP Authorization header with the "Bearer" scheme. The token attribute must be set to the value returned from the token request.

The token is passed with any requests to the main API endpoint (api.gb1.brightbox.com) in the following form:

GET /1.0/servers HTTP/1.1
Host: api.gb1.brightbox.com
Authorization: Bearer k1bjflpsaj8wnrbrwzad0eqo36nxiha

See https://tools.ietf.org/html/rfc6749#section-5.1

If the token is valid for the requested resource the response body is return. If the token is invalid or expired the response will be a 401 Unauthorised HTTP response with details of the error.

 HTTP/1.1 401 Unauthorized
 WWW-Authenticate: Bearer error='token_expired'

See https://tools.ietf.org/html/rfc6749#section-5.2

Request format

To make a request of the API the Content-Type of the request must be in JSON. See http://www.json.org/

The format of is that of a JSON object with a name for each attribute or link a resource has.

The JSON specification does not require an Object’s names and values to be ordered. Unrecognised parameters being sent will be ignored.

Representation format

The responses you receive from the API will be represented in JSON.

Each resource can be represented in one of three ways.

The format of is that of a JSON object with a name for each attribute or link a resource has.

Only the first level of a linked resource is shown as well as a url to access that resource.

The type of representation that is returned by an API action is detailed in the summary of each action.

Exact details of the response contents are included in the resource’s documentation.

The JSON specification does not require an Object’s names and values to be ordered. You should not expect the responses to return in a particular order since that is not guaranteed.

Examples of each type of representation are given near the resource’s main documentation

Full representation

Full representations show as much information about a resource as is possible. This includes all attributes for the resource. It also includes the nested representations for any other resources that are linked to the requested resource.

This allows you to see a summary of related resources without too many additional API requests.

Nested representation

Nested representations are shorter summaries of a resource intended to appear beneath a main resource.

A nested resource is named using the relationship between the two resources.

When a resource is collected to a number of other resources, this collection is represented using the nested representations rather than a collection representation.

Collected representation

Collected representations are used when the resource is a member of a collection. Some details are omitted since several sets of results are expected to be returned and including full details would create very large responses.

A collection representation is wrapped in an Array in the returned JSON response. This allows iteration across the collection.

Data type formats

Metadata service

The Brightbox cloud provides an EC2 compatible metadata service so that Servers are able to retrieve information about themselves while booting and whilst running. It is accessed via HTTP from the cloud server and uses IP-based authentication.

$ curl http://169.254.169.254/latest/meta-data
hostname
instance-id
instance-type
local-hostname
local-ipv4
placement/
public-ipv4
public-keys/

For example, to be able to retrieve the SSH public keys and add them to the authorized_keys file. The public SSH key associated with the User’s profile is available via this metadata service.

$ curl http://169.254.169.254/latest/meta-data/public-keys/usr-kl34r/openssh-key

This is already setup on the Official Brightbox Ubuntu images so you only need to worry about this if you are using your own image.

Custom metadata can be also be attached to a Server using the user_data attribute during creation. This data is treated as opaque and is stored and returned as application/octet-stream.

See the AWS Developer Guide for details.

Resources

Account

Brightbox services are provided through an Account. A typical customer will have at least one Account through which they buy their Servers and other services. They may create multiple accounts if they wish e.g to manage servers for separate clients of theirs.

Accounts have limits on the resources that they can use. These are currently:

Viewing current usage is possible via the Account show action or via the management control panel.

States

Attributes

Links

Representations

Full Account representation example

{"id": "acc-43ks4",
 "resource_type": "account",
 "url": "https://api.gb1.brightbox.com/1.0/accounts/acc-43ks4",
 "name": "Brightbox",
 "status": "active",
 "address_1": "Leeds Media Centre",
 "address_2": "21 Savile Mount",
 "city": "Leeds",
 "county": "",
 "postcode": "LS7 3HZ",
 "country_code": "GB",
 "country_name": "United Kingdom of Great Britain and Northern Ireland",
 "vat_registration_number": "GB916139623",
 "telephone_number": "+448456585545",
 "telephone_verified": true,
 "verified_telephone": "+448456585545",
 "verified_at": "2011-10-01T00:01:00Z",
 "verified_ip": "81.82.12.11",
 "created_at": "2011-10-01T00:00:00Z",
 "servers_used": 0,
 "ram_limit": 32768,
 "ram_used": 2048,
 "cloud_ips_limit": 10,
 "cloud_ips_used": 1,
 "load_balancers_limit": 30,
 "load_balancers_used": 1,
 "dbs_instances_used": 0,
 "dbs_ram_limit": 8192,
 "dbs_ram_used": 0,
 "valid_credit_card": true,
 "library_ftp_host": "ftp.library.gb1.brightbox.com",
 "library_ftp_user": "acc-43ks4",
 "library_ftp_password": null,
 "clients":
  [{"id": "cli-dsse2",
    "resource_type": "api_client",
    "url": "https://api.gb1.brightbox.com/1.0/api_clients/cli-dsse2",
    "name": "dev client",
    "description": "Development client from laptop",
    "revoked_at": null,
    "permissions_group": "full"}],
 "images":
  [],
 "servers":
  [],
 "load_balancers":
  [{"id": "lba-1235f",
    "resource_type": "load_balancer",
    "url": "https://api.gb1.brightbox.com/1.0/load_balancers/lba-1235f",
    "name": "",
    "status": "creating",
    "locked": false,
    "buffer_size": 4096,
    "https_redirect": false,
    "created_at": "2011-10-01T01:00:00Z",
    "deleted_at": null}],
 "database_servers":
  [],
 "database_snapshots":
  [],
 "cloud_ips":
  [{"id": "cip-k4a25",
    "resource_type": "cloud_ip",
    "url": "https://api.gb1.brightbox.com/1.0/cloud_ips/cip-k4a25",
    "status": "mapped",
    "public_ip": "109.107.50.0",
    "public_ipv4": "109.107.50.0",
    "public_ipv6": "2a02:1348:ffff:ffff::6d6b:3200",
    "fqdn": "cip-k4a25.gb1.brightbox.com",
    "reverse_dns": null,
    "name": "product website ip"}],
 "server_groups":
  [{"id": "grp-sda44",
    "resource_type": "server_group",
    "url": "https://api.gb1.brightbox.com/1.0/server_groups/grp-sda44",
    "name": "default",
    "description": null,
    "created_at": "2011-10-01T00:00:00Z",
    "default": true,
    "fqdn": "grp-sda44.gb1.brightbox.com"}],
 "firewall_policies":
  [{"id": "fwp-j3654",
    "resource_type": "firewall_policy",
    "url": "https://api.gb1.brightbox.com/1.0/firewall_policies/fwp-j3654",
    "default": true,
    "name": "default",
    "created_at": "2011-10-01T00:00:00Z",
    "description": null}],
 "owner":
  {"id": "usr-kl435",
   "resource_type": "user",
   "url": "https://api.gb1.brightbox.com/1.0/users/usr-kl435",
   "name": "John Jarvis",
   "email_address": "jjarvis@example.com",
   "2fa":
    {"enabled": false}},
 "users":
  [{"id": "usr-kl435",
    "resource_type": "user",
    "url": "https://api.gb1.brightbox.com/1.0/users/usr-kl435",
    "name": "John Jarvis",
    "email_address": "jjarvis@example.com",
    "2fa":
     {"enabled": false}}],
 "zones":
  [{"id": "zon-328ds",
    "resource_type": "zone",
    "url": "https://api.gb1.brightbox.com/1.0/zones/zon-328ds",
    "handle": "gb1"}]}

Collection Account representation example

[{"id": "acc-43ks4",
  "resource_type": "account",
  "url": "https://api.gb1.brightbox.com/1.0/accounts/acc-43ks4",
  "name": "Brightbox",
  "status": "active",
  "servers_used": 0,
  "ram_limit": 32768,
  "ram_used": 2048,
  "dbs_instances_used": 0,
  "dbs_ram_limit": 8192,
  "dbs_ram_used": 0,
  "cloud_ips_limit": 10,
  "cloud_ips_used": 1,
  "load_balancers_limit": 30,
  "load_balancers_used": 1,
  "clients":
   [{"id": "cli-dsse2",
     "resource_type": "api_client",
     "url": "https://api.gb1.brightbox.com/1.0/api_clients/cli-dsse2",
     "name": "dev client",
     "description": "Development client from laptop",
     "revoked_at": null,
     "permissions_group": "full"}],
  "images":
   [],
  "servers":
   [],
  "load_balancers":
   [{"id": "lba-1235f",
     "resource_type": "load_balancer",
     "url": "https://api.gb1.brightbox.com/1.0/load_balancers/lba-1235f",
     "name": "",
     "status": "creating",
     "locked": false,
     "buffer_size": 4096,
     "https_redirect": false,
     "created_at": "2011-10-01T01:00:00Z",
     "deleted_at": null}],
  "database_servers":
   [],
  "database_snapshots":
   [],
  "cloud_ips":
   [{"id": "cip-k4a25",
     "resource_type": "cloud_ip",
     "url": "https://api.gb1.brightbox.com/1.0/cloud_ips/cip-k4a25",
     "status": "mapped",
     "public_ip": "109.107.50.0",
     "public_ipv4": "109.107.50.0",
     "public_ipv6": "2a02:1348:ffff:ffff::6d6b:3200",
     "fqdn": "cip-k4a25.gb1.brightbox.com",
     "reverse_dns": null,
     "name": "product website ip"}],
  "server_groups":
   [{"id": "grp-sda44",
     "resource_type": "server_group",
     "url": "https://api.gb1.brightbox.com/1.0/server_groups/grp-sda44",
     "name": "default",
     "description": null,
     "created_at": "2011-10-01T00:00:00Z",
     "default": true,
     "fqdn": "grp-sda44.gb1.brightbox.com"}],
  "firewall_policies":
   [{"id": "fwp-j3654",
     "resource_type": "firewall_policy",
     "url": "https://api.gb1.brightbox.com/1.0/firewall_policies/fwp-j3654",
     "default": true,
     "name": "default",
     "created_at": "2011-10-01T00:00:00Z",
     "description": null}],
  "owner":
   {"id": "usr-kl435",
    "resource_type": "user",
    "url": "https://api.gb1.brightbox.com/1.0/users/usr-kl435",
    "name": "John Jarvis",
    "email_address": "jjarvis@example.com",
    "2fa":
     {"enabled": false}},
  "users":
   [{"id": "usr-kl435",
     "resource_type": "user",
     "url": "https://api.gb1.brightbox.com/1.0/users/usr-kl435",
     "name": "John Jarvis",
     "email_address": "jjarvis@example.com",
     "2fa":
      {"enabled": false}}],
  "zones":
   [{"id": "zon-328ds",
     "resource_type": "zone",
     "url": "https://api.gb1.brightbox.com/1.0/zones/zon-328ds",
     "handle": "gb1"}]}]

Nested Account representation example

{"id": "acc-43ks4",
 "resource_type": "account",
 "url": "https://api.gb1.brightbox.com/1.0/accounts/acc-43ks4",
 "name": "Brightbox",
 "status": "active"}

Actions

List request

Parameters

This action does not have any parameters.

Get request

Get full details of the account.

Parameters

This action does not have any parameters.

Update request

Update some details of the account.

Parameters

Reset ftp password request

Reset the image library ftp password for the account.

The response is the only time the new password is available in plaintext.

Parameters

This action does not have any parameters.

Api client

An application registered to an account in order to authenticate via OAuth2.0

Attributes

Links

Representations

Full Api client representation example

{"id": "cli-dsse2",
 "resource_type": "api_client",
 "url": "https://api.gb1.brightbox.com/1.0/api_clients/cli-dsse2",
 "name": "dev client",
 "description": "Development client from laptop",
 "secret": null,
 "revoked_at": null,
 "permissions_group": "full",
 "account":
  {"id": "acc-43ks4",
   "resource_type": "account",
   "url": "https://api.gb1.brightbox.com/1.0/accounts/acc-43ks4",
   "name": "Brightbox",
   "status": "active"}}

Collection Api client representation example

[{"id": "cli-dsse2",
  "resource_type": "api_client",
  "url": "https://api.gb1.brightbox.com/1.0/api_clients/cli-dsse2",
  "name": "dev client",
  "description": "Development client from laptop",
  "revoked_at": null,
  "permissions_group": "full",
  "account":
   {"id": "acc-43ks4",
    "resource_type": "account",
    "url": "https://api.gb1.brightbox.com/1.0/accounts/acc-43ks4",
    "name": "Brightbox",
    "status": "active"}}]

Nested Api client representation example

{"id": "cli-dsse2",
 "resource_type": "api_client",
 "url": "https://api.gb1.brightbox.com/1.0/api_clients/cli-dsse2",
 "name": "dev client",
 "description": "Development client from laptop",
 "revoked_at": null,
 "permissions_group": "full"}

Actions

List request

Lists summary details of API clients owned by the account.

Parameters

This action does not have any parameters.

Allowed Account states

This action can only be performed when the owning Account is in the following states:

• active
• overdue
• warning
• suspended
• closed

Create request

Create a new API client for the account.

Parameters

Allowed Account states

This action can only be performed when the owning Account is in the following states:

• active
• overdue
• warning
• closed

Get request

Get full details of the API client.

Parameters

This action does not have any parameters.

Allowed Account states

This action can only be performed when the owning Account is in the following states:

• active
• overdue
• warning
• suspended
• closed

Update request

Update some details of the API client.

Parameters

Allowed Account states

This action can only be performed when the owning Account is in the following states:

• active
• overdue
• warning
• closed

Delete request

Destroy the API client.

Parameters

This action does not have any parameters.

Allowed Account states

This action can only be performed when the owning Account is in the following states:

• active
• overdue
• warning
• closed

Reset secret request

Resets the secret used by the API client to a new generated value.

The response is the only time the new secret is available in plaintext.

Already authenticated tokens will still continue to be valid until expiry.

Parameters

This action does not have any parameters.

Allowed Account states

This action can only be performed when the owning Account is in the following states:

• active
• overdue
• warning
• closed

Cloud ip

A IPv4 publicly routed IP address that can be dynamically remapped.

States

Attributes

Links

Representations

Full Cloud ip representation example

{"id": "cip-k4a25",
 "resource_type": "cloud_ip",
 "url": "https://api.gb1.brightbox.com/1.0/cloud_ips/cip-k4a25",
 "status": "mapped",
 "public_ip": "109.107.50.0",
 "public_ipv4": "109.107.50.0",
 "public_ipv6": "2a02:1348:ffff:ffff::6d6b:3200",
 "fqdn": "cip-k4a25.gb1.brightbox.com",
 "reverse_dns": null,
 "port_translators":
  [{"protocol": "http",
    "incoming": 443,
    "outgoing": 2443}],
 "name": "product website ip",
 "account":
  {"id": "acc-43ks4",
   "resource_type": "account",
   "url": "https://api.gb1.brightbox.com/1.0/accounts/acc-43ks4",
   "name": "Brightbox",
   "status": "active"},
 "interface":
  {"id": "int-ds42k",
   "resource_type": "interface",
   "url": "https://api.gb1.brightbox.com/1.0/interfaces/int-ds42k",
   "mac_address": "02:24:19:00:00:ee",
   "ipv4_address": "81.15.16.17"},
 "server":
  {"id": "srv-lv426",
   "resource_type": "server",
   "url": "https://api.gb1.brightbox.com/1.0/servers/srv-lv426",
   "name": "",
   "status": "active",
   "locked": false,
   "hostname": "srv-lv426",
   "fqdn": "srv-lv426.gb1.brightbox.com",
   "created_at": "2011-10-01T01:00:00Z",
   "started_at": "2011-10-01T01:01:00Z",
   "deleted_at": null},
 "load_balancer": null,
 "server_group": null,
 "database_server": null}

Collection Cloud ip representation example

[{"id": "cip-k4a25",
  "resource_type": "cloud_ip",
  "url": "https://api.gb1.brightbox.com/1.0/cloud_ips/cip-k4a25",
  "status": "mapped",
  "public_ip": "109.107.50.0",
  "public_ipv4": "109.107.50.0",
  "public_ipv6": "2a02:1348:ffff:ffff::6d6b:3200",
  "fqdn": "cip-k4a25.gb1.brightbox.com",
  "reverse_dns": null,
  "port_translators":
   [{"protocol": "http",
     "incoming": 443,
     "outgoing": 2443}],
  "name": "product website ip",
  "account":
   {"id": "acc-43ks4",
    "resource_type": "account",
    "url": "https://api.gb1.brightbox.com/1.0/accounts/acc-43ks4",
    "name": "Brightbox",
    "status": "active"},
  "interface":
   {"id": "int-ds42k",
    "resource_type": "interface",
    "url": "https://api.gb1.brightbox.com/1.0/interfaces/int-ds42k",
    "mac_address": "02:24:19:00:00:ee",
    "ipv4_address": "81.15.16.17"},
  "server":
   {"id": "srv-lv426",
    "resource_type": "server",
    "url": "https://api.gb1.brightbox.com/1.0/servers/srv-lv426",
    "name": "",
    "status": "active",
    "locked": false,
    "hostname": "srv-lv426",
    "fqdn": "srv-lv426.gb1.brightbox.com",
    "created_at": "2011-10-01T01:00:00Z",
    "started_at": "2011-10-01T01:01:00Z",
    "deleted_at": null},
  "load_balancer": null,
  "server_group": null,
  "database_server": null}]

Nested Cloud ip representation example

{"id": "cip-k4a25",
 "resource_type": "cloud_ip",
 "url": "https://api.gb1.brightbox.com/1.0/cloud_ips/cip-k4a25",
 "status": "mapped",
 "public_ip": "109.107.50.0",
 "public_ipv4": "109.107.50.0",
 "public_ipv6": "2a02:1348:ffff:ffff::6d6b:3200",
 "fqdn": "cip-k4a25.gb1.brightbox.com",
 "reverse_dns": null,
 "name": "product website ip"}

Actions

List request

Lists summary details of cloud IP addresses owned by the account.

Parameters

This action does not have any parameters.

Allowed Account states

This action can only be performed when the owning Account is in the following states:

• active
• overdue
• warning
• suspended
• closed

Create request

Requests a new cloud IP address for the account.

Parameters

Allowed Account states

This action can only be performed when the owning Account is in the following states:

• active
• overdue
• warning
• closed

Get request

Get full details of the cloud IP address.

Parameters

This action does not have any parameters.

Allowed Account states

This action can only be performed when the owning Account is in the following states:

• active
• overdue
• warning
• suspended
• closed

Update request

Update some details of the cloud IP address.

Parameters

Allowed Account states

This action can only be performed when the owning Account is in the following states:

• active
• overdue
• warning
• closed

Delete request

Release the cloud IP address from the account’s ownership.

Parameters

This action does not have any parameters.

Allowed Account states

This action can only be performed when the owning Account is in the following states:

• active
• overdue
• warning
• suspended
• closed

Map request

Maps (or points) a cloud IP address at a server’s interface, load balancer, SQL instance or server group to allow them to respond to public requests.

Parameters

Allowed Account states

This action can only be performed when the owning Account is in the following states:

• active
• overdue
• warning
• closed

Unmap request

Unmaps a cloud IP address from its current destination making it available to remap. This remains in the account’s pool of addresses.

Parameters

This action does not have any parameters.

Allowed Account states

This action can only be performed when the owning Account is in the following states:

• active
• overdue
• warning
• suspended
• closed

Collaboration

A collaboration forms the link between an Account and a User, giving the User access to the specified Account. As a collaboration is created, the User is invited to accept the collaboration via email. The collaboration can be accepted or rejected via the User Collaboration’s accept or reject methods. Once the collaboration is complete either party can end the collaboration. Account administrators can call delete on the Collaboration or the User can call delete on the User Collaboration.

States

Attributes

Links

Representations

Full Collaboration representation example

{"id": null,
 "resource_type": "collaboration",
 "url": "https://api.gb1.brightbox.com/1.0/user/collaborations/",
 "status": "pending",
 "email": "tclock@example.com",
 "role": "admin",
 "created_at": "2013-03-24T00:00:00Z",
 "started_at": "2013-04-10T00:00:00Z",
 "finished_at": "2013-05-10T00:00:00Z",
 "role_label": "Collaborator",
 "user": null,
 "account":
  {"id": "acc-43ks4",
   "resource_type": "account",
   "url": "https://api.gb1.brightbox.com/1.0/accounts/acc-43ks4",
   "name": "Brightbox",
   "status": "active"},
 "inviter":
  {"id": "usr-kl435",
   "resource_type": "user",
   "url": "https://api.gb1.brightbox.com/1.0/users/usr-kl435",
   "name": "John Jarvis",
   "email_address": "jjarvis@example.com",
   "2fa":
    {"enabled": false}}}

Collection Collaboration representation example

[{"id": null,
  "resource_type": "collaboration",
  "url": "https://api.gb1.brightbox.com/1.0/user/collaborations/",
  "status": "pending",
  "email": "tclock@example.com",
  "role": "admin",
  "created_at": "2013-03-24T00:00:00Z",
  "started_at": "2013-04-10T00:00:00Z",
  "finished_at": "2013-05-10T00:00:00Z",
  "role_label": "Collaborator",
  "user": null,
  "account":
   {"id": "acc-43ks4",
    "resource_type": "account",
    "url": "https://api.gb1.brightbox.com/1.0/accounts/acc-43ks4",
    "name": "Brightbox",
    "status": "active"},
  "inviter":
   {"id": "usr-kl435",
    "resource_type": "user",
    "url": "https://api.gb1.brightbox.com/1.0/users/usr-kl435",
    "name": "John Jarvis",
    "email_address": "jjarvis@example.com",
    "2fa":
     {"enabled": false}}}]

Nested Collaboration representation example

{"id": null,
 "resource_type": "collaboration",
 "url": "https://api.gb1.brightbox.com/1.0/user/collaborations/",
 "status": "pending",
 "email": "tclock@example.com",
 "role": "admin",
 "created_at": "2013-03-24T00:00:00Z",
 "started_at": "2013-04-10T00:00:00Z",
 "finished_at": "2013-05-10T00:00:00Z",
 "role_label": "Collaborator"}

Actions

Create request

Invites the given email address to collaborate with the specified account. Existing users will be able to accept the collaboration whilst those without a Brightbox account will be invited to create one.

Parameters

Allowed Account states

This action can only be performed when the owning Account is in the following states:

• active
• overdue
• warning
• closed

List request

Lists all the collaborations for the given account

Parameters

This action does not have any parameters.

Allowed Account states

This action can only be performed when the owning Account is in the following states:

• active
• overdue
• warning
• closed

Get request

Shows details of the collaboration

Parameters

This action does not have any parameters.

Allowed Account states

This action can only be performed when the owning Account is in the following states:

• active
• overdue
• warning
• closed

Resend request

Resends the invitation email to the collaborator

Parameters

This action does not have any parameters.

Allowed Account states

This action can only be performed when the owning Account is in the following states:

• active
• overdue
• warning
• closed

Delete request

Cancels or completes the collaboration

Parameters

This action does not have any parameters.

Allowed Account states

This action can only be performed when the owning Account is in the following states:

• active
• overdue
• warning
• closed

Config map

A ConfigMap is a named collection of keys and values

Attributes

Representations

Full Config map representation example

{"id": null,
 "resource_type": "config_map",
 "url": "https://api.gb1.brightbox.com/1.0/config_maps/",
 "name": "example.test",
 "data":
  {"setting": 45}}

Collection Config map representation example

[{"id": null,
  "resource_type": "config_map",
  "url": "https://api.gb1.brightbox.com/1.0/config_maps/",
  "name": "example.test"}]

Nested Config map representation example

{"id": null,
 "resource_type": "config_map",
 "url": "https://api.gb1.brightbox.com/1.0/config_maps/",
 "name": "example.test"}

Actions

List request

Lists all ConfigMaps

Parameters

This action does not have any parameters.

Allowed Account states

This action can only be performed when the owning Account is in the following states:

• active
• overdue
• warning
• closed

Create request

Create a new ConfigMap.

Parameters

Allowed Account states

This action can only be performed when the owning Account is in the following states:

• active
• overdue
• warning
• closed

Get request

Get full details of the ConfigMap.

Parameters

This action does not have any parameters.

Allowed Account states

This action can only be performed when the owning Account is in the following states:

• active
• overdue
• warning
• closed

Update request

Update some details of the ConfigMap.

Parameters

Allowed Account states

This action can only be performed when the owning Account is in the following states:

• active
• overdue
• warning
• closed

Delete request

Delete the ConfigMap.

Parameters

This action does not have any parameters.

Allowed Account states

This action can only be performed when the owning Account is in the following states:

• active
• overdue
• warning
• closed

Database server

States

Attributes

Links

Representations

Full Database server representation example

{"id": "dbs-123ab",
 "resource_type": "database_server",
 "url": "https://api.gb1.brightbox.com/1.0/database_servers/dbs-123ab",
 "name": "My Database Server",
 "description": "Application one's DBS",
 "admin_username": "admin",
 "admin_password": null,
 "allow_access":
  [],
 "database_engine": "mysql",
 "database_version": "5.5",
 "status": "active",
 "locked": false,
 "maintenance_weekday": 0,
 "maintenance_hour": 6,
 "snapshots_schedule": null,
 "snapshots_schedule_next_at": null,
 "created_at": "2011-10-01T01:00:00Z",
 "updated_at": "2011-11-01T01:00:00Z",
 "deleted_at": null,
 "account":
  {"id": "acc-43ks4",
   "resource_type": "account",
   "url": "https://api.gb1.brightbox.com/1.0/accounts/acc-43ks4",
   "name": "Brightbox",
   "status": "active"},
 "database_server_type":
  {"id": "dbt-12345",
   "resource_type": "database_type",
   "url": "https://api.gb1.brightbox.com/1.0/database_types/dbt-12345",
   "name": "Small",
   "description": "Database Type Small",
   "disk_size": 81920,
   "ram": 2048,
   "default": false},
 "cloud_ips":
  [],
 "zone":
  {"id": "zon-328ds",
   "resource_type": "zone",
   "url": "https://api.gb1.brightbox.com/1.0/zones/zon-328ds",
   "handle": "gb1"}}

Collection Database server representation example

[{"id": "dbs-123ab",
  "resource_type": "database_server",
  "url": "https://api.gb1.brightbox.com/1.0/database_servers/dbs-123ab",
  "name": "My Database Server",
  "description": "Application one's DBS",
  "allow_access":
   [],
  "database_engine": "mysql",
  "database_version": "5.5",
  "status": "active",
  "locked": false,
  "maintenance_weekday": 0,
  "maintenance_hour": 6,
  "snapshots_schedule": null,
  "snapshots_schedule_next_at": null,
  "created_at": "2011-10-01T01:00:00Z",
  "updated_at": "2011-11-01T01:00:00Z",
  "deleted_at": null,
  "account":
   {"id": "acc-43ks4",
    "resource_type": "account",
    "url": "https://api.gb1.brightbox.com/1.0/accounts/acc-43ks4",
    "name": "Brightbox",
    "status": "active"},
  "database_server_type":
   {"id": "dbt-12345",
    "resource_type": "database_type",
    "url": "https://api.gb1.brightbox.com/1.0/database_types/dbt-12345",
    "name": "Small",
    "description": "Database Type Small",
    "disk_size": 81920,
    "ram": 2048,
    "default": false},
  "cloud_ips":
   [],
  "zone":
   {"id": "zon-328ds",
    "resource_type": "zone",
    "url": "https://api.gb1.brightbox.com/1.0/zones/zon-328ds",
    "handle": "gb1"}}]

Nested Database server representation example

{"id": "dbs-123ab",
 "resource_type": "database_server",
 "url": "https://api.gb1.brightbox.com/1.0/database_servers/dbs-123ab",
 "name": "My Database Server",
 "description": "Application one's DBS",
 "allow_access":
  [],
 "database_engine": "mysql",
 "database_version": "5.5",
 "status": "active",
 "locked": false,
 "maintenance_weekday": 0,
 "maintenance_hour": 6,
 "created_at": "2011-10-01T01:00:00Z",
 "updated_at": "2011-11-01T01:00:00Z",
 "deleted_at": null}

Actions

List request

Parameters

This action does not have any parameters.

Allowed Account states

This action can only be performed when the owning Account is in the following states:

• active
• overdue
• warning
• suspended
• closed

Create request

Parameters

Allowed Account states

This action can only be performed when the owning Account is in the following states:

• active
• overdue
• warning
• closed

Get request

Parameters

This action does not have any parameters.

Allowed Account states

This action can only be performed when the owning Account is in the following states:

• active
• overdue
• warning
• suspended
• closed

Update request

Parameters

Allowed Account states

This action can only be performed when the owning Account is in the following states:

• active
• overdue
• warning
• closed

Delete request

Parameters

This action does not have any parameters.

Allowed Account states

This action can only be performed when the owning Account is in the following states:

• active
• overdue
• warning
• suspended
• closed

Snapshot request

Requests a snapshot of the database server to be made for restoring back to when it was made. The identifier of the new snapshot is returned by the response in a Link header

Parameters

This action does not have any parameters.

Allowed Account states

This action can only be performed when the owning Account is in the following states:

• active
• overdue
• warning
• closed

Reset password request

This requests the admin password for the database server is reset. The new admin_password is only returned in the JSON response to this request.

Parameters

This action does not have any parameters.

Allowed Account states

This action can only be performed when the owning Account is in the following states:

• active
• overdue
• warning
• closed

Lock resource request

Parameters

This action does not have any parameters.

Allowed Account states

This action can only be performed when the owning Account is in the following states:

• active
• overdue
• warning
• closed

Unlock resource request

Parameters

This action does not have any parameters.

Allowed Account states

This action can only be performed when the owning Account is in the following states:

• active
• overdue
• warning
• closed

Database snapshot

States

Attributes

Representations

Full Database snapshot representation example

{"id": "dbi-12345",
 "resource_type": "database_snapshot",
 "url": "https://api.gb1.brightbox.com/1.0/database_snapshots/dbi-12345",
 "name": "Snapshot of dbs-123ab 1 Nov 01:00",
 "description": "",
 "status": "available",
 "locked": false,
 "database_engine": "mysql",
 "database_version": "5.5",
 "source": null,
 "size": 0,
 "created_at": "2011-10-01T01:00:00Z",
 "updated_at": "2011-11-01T01:00:00Z",
 "deleted_at": null,
 "account":
  {"id": "acc-43ks4",
   "resource_type": "account",
   "url": "https://api.gb1.brightbox.com/1.0/accounts/acc-43ks4",
   "name": "Brightbox",
   "status": "active"}}

Collection Database snapshot representation example

[{"id": "dbi-12345",
  "resource_type": "database_snapshot",
  "url": "https://api.gb1.brightbox.com/1.0/database_snapshots/dbi-12345",
  "name": "Snapshot of dbs-123ab 1 Nov 01:00",
  "description": "",
  "status": "available",
  "locked": false,
  "database_engine": "mysql",
  "database_version": "5.5",
  "source": null,
  "size": 0,
  "created_at": "2011-10-01T01:00:00Z",
  "updated_at": "2011-11-01T01:00:00Z",
  "deleted_at": null,
  "account":
   {"id": "acc-43ks4",
    "resource_type": "account",
    "url": "https://api.gb1.brightbox.com/1.0/accounts/acc-43ks4",
    "name": "Brightbox",
    "status": "active"}}]

Nested Database snapshot representation example

{"id": "dbi-12345",
 "resource_type": "database_snapshot",
 "url": "https://api.gb1.brightbox.com/1.0/database_snapshots/dbi-12345",
 "name": "Snapshot of dbs-123ab 1 Nov 01:00",
 "description": "",
 "status": "available",
 "locked": false,
 "database_engine": "mysql",
 "database_version": "5.5",
 "source": null,
 "size": 0,
 "created_at": "2011-10-01T01:00:00Z",
 "updated_at": "2011-11-01T01:00:00Z",
 "deleted_at": null}

Actions

List request

Parameters

This action does not have any parameters.

Allowed Account states

This action can only be performed when the owning Account is in the following states:

• active
• overdue
• warning
• suspended
• closed

Get request

Parameters

This action does not have any parameters.

Allowed Account states

This action can only be performed when the owning Account is in the following states:

• active
• overdue
• warning
• suspended
• closed

Update request

Update some details of the server.

Parameters

Allowed Account states

This action can only be performed when the owning Account is in the following states:

• active
• overdue
• warning
• closed

Delete request

Parameters

This action does not have any parameters.

Allowed Account states

This action can only be performed when the owning Account is in the following states:

• active
• overdue
• warning
• suspended
• closed

Lock resource request

Parameters

This action does not have any parameters.

Allowed Account states

This action can only be performed when the owning Account is in the following states:

• active
• overdue
• warning
• closed

Unlock resource request

Parameters

This action does not have any parameters.

Allowed Account states

This action can only be performed when the owning Account is in the following states:

• active
• overdue
• warning
• closed

Database type

All Database Servers are created with a type. The type represents the available RAM and Disk space of the Server.

Attributes

Representations

Full Database type representation example

{"id": "dbt-12345",
 "resource_type": "database_type",
 "url": "https://api.gb1.brightbox.com/1.0/database_types/dbt-12345",
 "name": "Small",
 "description": "Database Type Small",
 "disk_size": 81920,
 "ram": 2048,
 "default": false}

Collection Database type representation example

[{"id": "dbt-12345",
  "resource_type": "database_type",
  "url": "https://api.gb1.brightbox.com/1.0/database_types/dbt-12345",
  "name": "Small",
  "description": "Database Type Small",
  "disk_size": 81920,
  "ram": 2048,
  "default": false}]

Nested Database type representation example

{"id": "dbt-12345",
 "resource_type": "database_type",
 "url": "https://api.gb1.brightbox.com/1.0/database_types/dbt-12345",
 "name": "Small",
 "description": "Database Type Small",
 "disk_size": 81920,
 "ram": 2048,
 "default": false}

Actions

List request

List database server types.

Parameters

This action does not have any parameters.

Get request

Get details of the database server type.

Parameters

This action does not have any parameters.

Firewall policy

A collection of Firewall Rules

Attributes

Links

Representations

Full Firewall policy representation example

{"id": "fwp-j3654",
 "resource_type": "firewall_policy",
 "url": "https://api.gb1.brightbox.com/1.0/firewall_policies/fwp-j3654",
 "default": true,
 "name": "default",
 "created_at": "2011-10-01T00:00:00Z",
 "description": null,
 "account":
  {"id": "acc-43ks4",
   "resource_type": "account",
   "url": "https://api.gb1.brightbox.com/1.0/accounts/acc-43ks4",
   "name": "Brightbox",
   "status": "active"},
 "server_group":
  {"id": "grp-sda44",
   "resource_type": "server_group",
   "url": "https://api.gb1.brightbox.com/1.0/server_groups/grp-sda44",
   "name": "default",
   "description": null,
   "created_at": "2011-10-01T00:00:00Z",
   "default": true,
   "fqdn": "grp-sda44.gb1.brightbox.com"},
 "rules":
  [{"id": "fwr-k32ls",
    "resource_type": "firewall_rule",
    "url": "https://api.gb1.brightbox.com/1.0/firewall_rules/fwr-k32ls",
    "source": "srv-lv426",
    "source_port": "80,443,21",
    "destination": null,
    "destination_port": null,
    "protocol": "tcp",
    "icmp_type_name": null,
    "description": null,
    "created_at": "2011-10-01T00:00:00Z"}]}

Collection Firewall policy representation example

[{"id": "fwp-j3654",
  "resource_type": "firewall_policy",
  "url": "https://api.gb1.brightbox.com/1.0/firewall_policies/fwp-j3654",
  "default": true,
  "name": "default",
  "created_at": "2011-10-01T00:00:00Z",
  "description": null,
  "account":
   {"id": "acc-43ks4",
    "resource_type": "account",
    "url": "https://api.gb1.brightbox.com/1.0/accounts/acc-43ks4",
    "name": "Brightbox",
    "status": "active"},
  "server_group":
   {"id": "grp-sda44",
    "resource_type": "server_group",
    "url": "https://api.gb1.brightbox.com/1.0/server_groups/grp-sda44",
    "name": "default",
    "description": null,
    "created_at": "2011-10-01T00:00:00Z",
    "default": true,
    "fqdn": "grp-sda44.gb1.brightbox.com"},
  "rules":
   [{"id": "fwr-k32ls",
     "resource_type": "firewall_rule",
     "url": "https://api.gb1.brightbox.com/1.0/firewall_rules/fwr-k32ls",
     "source": "srv-lv426",
     "source_port": "80,443,21",
     "destination": null,
     "destination_port": null,
     "protocol": "tcp",
     "icmp_type_name": null,
     "description": null,
     "created_at": "2011-10-01T00:00:00Z"}]}]

Nested Firewall policy representation example

{"id": "fwp-j3654",
 "resource_type": "firewall_policy",
 "url": "https://api.gb1.brightbox.com/1.0/firewall_policies/fwp-j3654",
 "default": true,
 "name": "default",
 "created_at": "2011-10-01T00:00:00Z",
 "description": null}

Actions

List request

Lists summary details of firewall policies

Parameters

This action does not have any parameters.

Allowed Account states

This action can only be performed when the owning Account is in the following states:

• active
• overdue
• warning
• suspended
• closed

Create request

Create a new firewall policy for the account.

Optionally applying to a server group at creation time.

Parameters

Allowed Account states

This action can only be performed when the owning Account is in the following states:

• active
• overdue
• warning
• closed

Get request

Get details of the firewall policy

Parameters

This action does not have any parameters.

Allowed Account states

This action can only be performed when the owning Account is in the following states:

• active
• overdue
• warning
• suspended
• closed

Update request

Updates details of the firewall policy

Parameters

Allowed Account states

This action can only be performed when the owning Account is in the following states:

• active
• overdue
• warning
• suspended
• closed

Apply to request

Applies firewall policy to given server group

Parameters

Allowed Account states

This action can only be performed when the owning Account is in the following states:

• active
• overdue
• warning
• closed

Remove request

Removes firewall policy from given server group

Parameters

Allowed Account states

This action can only be performed when the owning Account is in the following states:

• active
• overdue
• warning
• closed

Delete request

Destroy the firewall policy if not in use.

Parameters

This action does not have any parameters.

Allowed Account states

This action can only be performed when the owning Account is in the following states:

• active
• overdue
• warning
• closed

Firewall rule

A firewall rule representing a single ‘ACCEPT’ rule

Attributes

Links

Representations

Full Firewall rule representation example

{"id": "fwr-k32ls",
 "resource_type": "firewall_rule",
 "url": "https://api.gb1.brightbox.com/1.0/firewall_rules/fwr-k32ls",
 "source": "srv-lv426",
 "source_port": "80,443,21",
 "destination": null,
 "destination_port": null,
 "icmp_type_name": null,
 "protocol": "tcp",
 "description": null,
 "created_at": "2011-10-01T00:00:00Z",
 "firewall_policy":
  {"id": "fwp-j3654",
   "resource_type": "firewall_policy",
   "url": "https://api.gb1.brightbox.com/1.0/firewall_policies/fwp-j3654",
   "default": true,
   "name": "default",
   "created_at": "2011-10-01T00:00:00Z",
   "description": null}}

Collection Firewall rule representation example

[{"id": "fwr-k32ls",
  "resource_type": "firewall_rule",
  "url": "https://api.gb1.brightbox.com/1.0/firewall_rules/fwr-k32ls",
  "source": "srv-lv426",
  "source_port": "80,443,21",
  "destination": null,
  "destination_port": null,
  "protocol": "tcp",
  "icmp_type_name": null,
  "description": null,
  "created_at": "2011-10-01T00:00:00Z",
  "firewall_policy":
   {"id": "fwp-j3654",
    "resource_type": "firewall_policy",
    "url": "https://api.gb1.brightbox.com/1.0/firewall_policies/fwp-j3654",
    "default": true,
    "name": "default",
    "created_at": "2011-10-01T00:00:00Z",
    "description": null}}]

Nested Firewall rule representation example

{"id": "fwr-k32ls",
 "resource_type": "firewall_rule",
 "url": "https://api.gb1.brightbox.com/1.0/firewall_rules/fwr-k32ls",
 "source": "srv-lv426",
 "source_port": "80,443,21",
 "destination": null,
 "destination_port": null,
 "protocol": "tcp",
 "icmp_type_name": null,
 "description": null,
 "created_at": "2011-10-01T00:00:00Z"}

Actions

Create request

Create a new firewall rule for a firewall policy.

Parameters

Get request

Get full details of the firewall rule.

Parameters

This action does not have any parameters.

Update request

Update some settings of the firewall rule.

Parameters

Delete request

Destroy the firewall rule.

Parameters

This action does not have any parameters.

Image

An Image is virtual disk image used as the basis of the server.

States

Attributes

Links

Representations

Full Image representation example

{"id": "img-3ikco",
 "resource_type": "image",
 "url": "https://api.gb1.brightbox.com/1.0/images/img-3ikco",
 "name": "Ubuntu Lucid 10.04 server",
 "status": "available",
 "locked": false,
 "username": "ubuntu",
 "description": "Expands root partition automatically. login: ubuntu using stored ssh key",
 "source": "ubuntu-lucid-daily-i64-server-20110509",
 "arch": "x86_64",
 "created_at": "2011-05-09T12:00:00Z",
 "official": true,
 "public": true,
 "compatibility_mode": false,
 "source_type": "upload",
 "disk_size": 560,
 "virtual_size": 1409,
 "min_ram": null,
 "owner": "acc-43ks4",
 "licence_name": "Windows 2008",
 "ancestor": null}

Collection Image representation example

[{"id": "img-3ikco",
  "resource_type": "image",
  "url": "https://api.gb1.brightbox.com/1.0/images/img-3ikco",
  "name": "Ubuntu Lucid 10.04 server",
  "username": "ubuntu",
  "status": "available",
  "locked": false,
  "description": "Expands root partition automatically. login: ubuntu using stored ssh key",
  "source": "ubuntu-lucid-daily-i64-server-20110509",
  "arch": "x86_64",
  "created_at": "2011-05-09T12:00:00Z",
  "owner": "acc-43ks4",
  "official": true,
  "public": true,
  "compatibility_mode": false,
  "source_type": "upload",
  "disk_size": 560,
  "virtual_size": 1409,
  "min_ram": null,
  "ancestor": null}]

Nested Image representation example

{"id": "img-3ikco",
 "resource_type": "image",
 "url": "https://api.gb1.brightbox.com/1.0/images/img-3ikco",
 "name": "Ubuntu Lucid 10.04 server",
 "username": "ubuntu",
 "status": "available",
 "locked": false,
 "description": "Expands root partition automatically. login: ubuntu using stored ssh key",
 "source": "ubuntu-lucid-daily-i64-server-20110509",
 "arch": "x86_64",
 "created_at": "2011-05-09T12:00:00Z",
 "official": true,
 "public": true,
 "owner": "acc-43ks4"}

Actions

List request

Lists summary details of images available for use by the Account. It includes those available to all customers

Parameters

This action does not have any parameters.

Allowed Account states

This action can only be performed when the owning Account is in the following states:

• pending
• active
• overdue
• warning
• suspended
• closed

Create request

Create a new image for the account by registering it against an image stored within the Brightbox cloud image library.

The disk image must be in place before you can attempt to create a reference in the API.

Parameters

Allowed Account states

This action can only be performed when the owning Account is in the following states:

• active
• overdue
• warning
• closed

Get request

Get full details of the image.

Parameters

This action does not have any parameters.

Allowed Account states

This action can only be performed when the owning Account is in the following states:

• pending
• active
• overdue
• warning
• suspended
• closed

Update request

Update some details of the image.

Parameters

Allowed Account states

This action can only be performed when the owning Account is in the following states:

• active
• overdue
• warning
• closed

Delete request

Destroy the image.

Parameters

This action does not have any parameters.

Allowed Account states

This action can only be performed when the owning Account is in the following states:

• active
• overdue
• warning
• suspended
• closed

Lock resource request

Parameters

This action does not have any parameters.

Allowed Account states

This action can only be performed when the owning Account is in the following states:

• active
• overdue
• warning
• closed

Unlock resource request

Parameters

This action does not have any parameters.

Allowed Account states

This action can only be performed when the owning Account is in the following states:

• active
• overdue
• warning
• closed

Interface

An Interface resource represents the network interface of a Server. Each Server has one Interface, created automatically when the Server is created. An interface has an IPv4 ("local") address and, optionally, an IPv6 ("public") address.

Future versions of the API should support creation of multiple Interfaces per Server to enable, for example, multiple SSL applications per server.

Attributes

Links

Representations

Full Interface representation example

{"id": "int-ds42k",
 "resource_type": "interface",
 "url": "https://api.gb1.brightbox.com/1.0/interfaces/int-ds42k",
 "mac_address": "02:24:19:00:00:ee",
 "ipv4_address": "81.15.16.17",
 "server": null}

Collection Interface representation example

[{"id": "int-ds42k",
  "resource_type": "interface",
  "url": "https://api.gb1.brightbox.com/1.0/interfaces/int-ds42k",
  "mac_address": "02:24:19:00:00:ee",
  "ipv4_address": "81.15.16.17",
  "server": null}]

Nested Interface representation example

{"id": "int-ds42k",
 "resource_type": "interface",
 "url": "https://api.gb1.brightbox.com/1.0/interfaces/int-ds42k",
 "mac_address": "02:24:19:00:00:ee",
 "ipv4_address": "81.15.16.17"}

Actions

Get request

Get full details of the interface.

Parameters

This action does not have any parameters.

Load balancer

A load balancer balances requests between multiple servers

States

Attributes

Links

Representations

Full Load balancer representation example

{"id": "lba-1235f",
 "resource_type": "load_balancer",
 "url": "https://api.gb1.brightbox.com/1.0/load_balancers/lba-1235f",
 "name": "",
 "status": "creating",
 "locked": false,
 "created_at": "2011-10-01T01:00:00Z",
 "deleted_at": null,
 "policy": "least-connections",
 "buffer_size": 4096,
 "https_redirect": false,
 "listeners":
  [{"protocol": "http",
    "in": 80,
    "out": 80,
    "timeout": 50000,
    "proxy_protocol": null}],
 "healthcheck":
  {"type": "http",
   "request": "/",
   "port": 80,
   "interval": 5000,
   "timeout": 5000,
   "threshold_up": 3,
   "threshold_down": 3},
 "acme":
  {"certificate": null,
   "domains":
    []},
 "ssl_minimum_version": "TLSv1.2",
 "certificate": null,
 "account":
  {"id": "acc-43ks4",
   "resource_type": "account",
   "url": "https://api.gb1.brightbox.com/1.0/accounts/acc-43ks4",
   "name": "Brightbox",
   "status": "active"},
 "cloud_ips":
  [],
 "nodes":
  [{"id": "srv-lv426",
    "resource_type": "server",
    "url": "https://api.gb1.brightbox.com/1.0/servers/srv-lv426",
    "name": "",
    "status": "active",
    "locked": false,
    "hostname": "srv-lv426",
    "fqdn": "srv-lv426.gb1.brightbox.com",
    "created_at": "2011-10-01T01:00:00Z",
    "started_at": "2011-10-01T01:01:00Z",
    "deleted_at": null}]}

Collection Load balancer representation example

[{"id": "lba-1235f",
  "resource_type": "load_balancer",
  "url": "https://api.gb1.brightbox.com/1.0/load_balancers/lba-1235f",
  "name": "",
  "status": "creating",
  "locked": false,
  "created_at": "2011-10-01T01:00:00Z",
  "deleted_at": null,
  "policy": "least-connections",
  "buffer_size": 4096,
  "https_redirect": false,
  "listeners":
   [{"protocol": "http",
     "in": 80,
     "out": 80,
     "timeout": 50000,
     "proxy_protocol": null}],
  "healthcheck":
   {"type": "http",
    "request": "/",
    "port": 80,
    "interval": 5000,
    "timeout": 5000,
    "threshold_up": 3,
    "threshold_down": 3},
  "account":
   {"id": "acc-43ks4",
    "resource_type": "account",
    "url": "https://api.gb1.brightbox.com/1.0/accounts/acc-43ks4",
    "name": "Brightbox",
    "status": "active"},
  "cloud_ips":
   [],
  "nodes":
   [{"id": "srv-lv426",
     "resource_type": "server",
     "url": "https://api.gb1.brightbox.com/1.0/servers/srv-lv426",
     "name": "",
     "status": "active",
     "locked": false,
     "hostname": "srv-lv426",
     "fqdn": "srv-lv426.gb1.brightbox.com",
     "created_at": "2011-10-01T01:00:00Z",
     "started_at": "2011-10-01T01:01:00Z",
     "deleted_at": null}]}]

Nested Load balancer representation example

{"id": "lba-1235f",
 "resource_type": "load_balancer",
 "url": "https://api.gb1.brightbox.com/1.0/load_balancers/lba-1235f",
 "name": "",
 "status": "creating",
 "locked": false,
 "buffer_size": 4096,
 "https_redirect": false,
 "created_at": "2011-10-01T01:00:00Z",
 "deleted_at": null}

Actions

List request

Lists summary details of load balancers owned by the account.

Parameters

This action does not have any parameters.

Allowed Account states

This action can only be performed when the owning Account is in the following states:

• active
• overdue
• warning
• suspended
• closed

Create request

Create a new load balancer for the account.

Parameters

Allowed Account states

This action can only be performed when the owning Account is in the following states:

• active
• overdue
• warning
• closed

Get request

Get full details of the load balancer.

Parameters

This action does not have any parameters.

Allowed Account states

This action can only be performed when the owning Account is in the following states:

• active
• overdue
• warning
• suspended
• closed

Update request

Update some details of the load balancer.

Parameters

Allowed Account states

This action can only be performed when the owning Account is in the following states:

• active
• overdue
• warning
• closed

Add nodes request

Add a number of nodes to the load balancer

Parameters

Allowed Account states

This action can only be performed when the owning Account is in the following states:

• active
• overdue
• warning
• closed

Remove nodes request

Remove a number of nodes from the load balancer

Parameters

Allowed Account states

This action can only be performed when the owning Account is in the following states:

• active
• overdue
• warning
• suspended
• closed

Add listeners request

Adds a number of listeners to the load balancer to enable balancing across nodes for those settings.

Parameters

Allowed Account states

This action can only be performed when the owning Account is in the following states:

• active
• overdue
• warning
• closed

Remove listeners request

Removes a number of listeners from a load balancer to cease balancing across nodes for those settings.

Parameters

Allowed Account states

This action can only be performed when the owning Account is in the following states:

• active
• overdue
• warning
• suspended
• closed

Delete request

Destroy the LoadBalancer

Parameters

This action does not have any parameters.

Allowed Account states

This action can only be performed when the owning Account is in the following states:

• active
• overdue
• warning
• suspended
• closed

Lock resource request

Parameters

This action does not have any parameters.

Allowed Account states

This action can only be performed when the owning Account is in the following states:

• active
• overdue
• warning
• closed

Unlock resource request

Parameters

This action does not have any parameters.

Allowed Account states

This action can only be performed when the owning Account is in the following states:

• active
• overdue
• warning
• closed

Server

A Server is a single cloud virtual machine running an operating system defined by the Image used to create it. There are several specifications of servers (Server Types) available.

The only required argument (at this time) is the Image you would like to use for the server. All other values will use a default value.

States

Attributes

Links

Representations

Full Server representation example

{"id": "srv-lv426",
 "resource_type": "server",
 "url": "https://api.gb1.brightbox.com/1.0/servers/srv-lv426",
 "name": "",
 "status": "active",
 "locked": false,
 "hostname": "srv-lv426",
 "created_at": "2011-10-01T01:00:00Z",
 "started_at": "2011-10-01T01:01:00Z",
 "deleted_at": null,
 "user_data": null,
 "fqdn": "srv-lv426.gb1.brightbox.com",
 "compatibility_mode": false,
 "console_url": null,
 "console_token": null,
 "console_token_expires": null,
 "disk_encrypted": false,
 "account":
  {"id": "acc-43ks4",
   "resource_type": "account",
   "url": "https://api.gb1.brightbox.com/1.0/accounts/acc-43ks4",
   "name": "Brightbox",
   "status": "active"},
 "image":
  {"id": "img-3ikco",
   "resource_type": "image",
   "url": "https://api.gb1.brightbox.com/1.0/images/img-3ikco",
   "name": "Ubuntu Lucid 10.04 server",
   "username": "ubuntu",
   "status": "available",
   "locked": false,
   "description": "Expands root partition automatically. login: ubuntu using stored ssh key",
   "source": "ubuntu-lucid-daily-i64-server-20110509",
   "arch": "x86_64",
   "created_at": "2011-05-09T12:00:00Z",
   "official": true,
   "public": true,
   "owner": "acc-43ks4"},
 "server_type":
  {"id": "typ-zx45f",
   "resource_type": "server_type",
   "url": "https://api.gb1.brightbox.com/1.0/server_types/typ-zx45f",
   "name": "Small",
   "status": "available",
   "cores": 2,
   "ram": 2048,
   "disk_size": 81920,
   "handle": "small"},
 "zone":
  {"id": "zon-328ds",
   "resource_type": "zone",
   "url": "https://api.gb1.brightbox.com/1.0/zones/zon-328ds",
   "handle": "gb1"},
 "cloud_ips":
  [{"id": "cip-k4a25",
    "resource_type": "cloud_ip",
    "url": "https://api.gb1.brightbox.com/1.0/cloud_ips/cip-k4a25",
    "status": "mapped",
    "public_ip": "109.107.50.0",
    "public_ipv4": "109.107.50.0",
    "public_ipv6": "2a02:1348:ffff:ffff::6d6b:3200",
    "fqdn": "cip-k4a25.gb1.brightbox.com",
    "reverse_dns": null,
    "name": "product website ip"}],
 "interfaces":
  [{"id": "int-ds42k",
    "resource_type": "interface",
    "url": "https://api.gb1.brightbox.com/1.0/interfaces/int-ds42k",
    "mac_address": "02:24:19:00:00:ee",
    "ipv4_address": "81.15.16.17"}],
 "snapshots":
  [],
 "server_groups":
  [{"id": "grp-sda44",
    "resource_type": "server_group",
    "url": "https://api.gb1.brightbox.com/1.0/server_groups/grp-sda44",
    "name": "default",
    "description": null,
    "created_at": "2011-10-01T00:00:00Z",
    "default": true,
    "fqdn": "grp-sda44.gb1.brightbox.com"}]}

Collection Server representation example

[{"id": "srv-lv426",
  "resource_type": "server",
  "url": "https://api.gb1.brightbox.com/1.0/servers/srv-lv426",
  "name": "",
  "status": "active",
  "locked": false,
  "hostname": "srv-lv426",
  "fqdn": "srv-lv426.gb1.brightbox.com",
  "compatibility_mode": false,
  "created_at": "2011-10-01T01:00:00Z",
  "started_at": "2011-10-01T01:01:00Z",
  "deleted_at": null,
  "account":
   {"id": "acc-43ks4",
    "resource_type": "account",
    "url": "https://api.gb1.brightbox.com/1.0/accounts/acc-43ks4",
    "name": "Brightbox",
    "status": "active"},
  "image":
   {"id": "img-3ikco",
    "resource_type": "image",
    "url": "https://api.gb1.brightbox.com/1.0/images/img-3ikco",
    "name": "Ubuntu Lucid 10.04 server",
    "username": "ubuntu",
    "status": "available",
    "locked": false,
    "description": "Expands root partition automatically. login: ubuntu using stored ssh key",
    "source": "ubuntu-lucid-daily-i64-server-20110509",
    "arch": "x86_64",
    "created_at": "2011-05-09T12:00:00Z",
    "official": true,
    "public": true,
    "owner": "acc-43ks4"},
  "server_type":
   {"id": "typ-zx45f",
    "resource_type": "server_type",
    "url": "https://api.gb1.brightbox.com/1.0/server_types/typ-zx45f",
    "name": "Small",
    "status": "available",
    "cores": 2,
    "ram": 2048,
    "disk_size": 81920,
    "handle": "small"},
  "zone":
   {"id": "zon-328ds",
    "resource_type": "zone",
    "url": "https://api.gb1.brightbox.com/1.0/zones/zon-328ds",
    "handle": "gb1"},
  "cloud_ips":
   [{"id": "cip-k4a25",
     "resource_type": "cloud_ip",
     "url": "https://api.gb1.brightbox.com/1.0/cloud_ips/cip-k4a25",
     "status": "mapped",
     "public_ip": "109.107.50.0",
     "public_ipv4": "109.107.50.0",
     "public_ipv6": "2a02:1348:ffff:ffff::6d6b:3200",
     "fqdn": "cip-k4a25.gb1.brightbox.com",
     "reverse_dns": null,
     "name": "product website ip"}],
  "interfaces":
   [{"id": "int-ds42k",
     "resource_type": "interface",
     "url": "https://api.gb1.brightbox.com/1.0/interfaces/int-ds42k",
     "mac_address": "02:24:19:00:00:ee",
     "ipv4_address": "81.15.16.17"}],
  "snapshots":
   [],
  "server_groups":
   [{"id": "grp-sda44",
     "resource_type": "server_group",
     "url": "https://api.gb1.brightbox.com/1.0/server_groups/grp-sda44",
     "name": "default",
     "description": null,
     "created_at": "2011-10-01T00:00:00Z",
     "default": true,
     "fqdn": "grp-sda44.gb1.brightbox.com"}]}]

Nested Server representation example

{"id": "srv-lv426",
 "resource_type": "server",
 "url": "https://api.gb1.brightbox.com/1.0/servers/srv-lv426",
 "name": "",
 "status": "active",
 "locked": false,
 "hostname": "srv-lv426",
 "fqdn": "srv-lv426.gb1.brightbox.com",
 "created_at": "2011-10-01T01:00:00Z",
 "started_at": "2011-10-01T01:01:00Z",
 "deleted_at": null}

Actions

List request

Lists summary details of servers owned by the account.

Parameters

This action does not have any parameters.

Allowed Account states

This action can only be performed when the owning Account is in the following states:

• active
• overdue
• warning
• suspended
• closed

Create request

Create a new server for the account based on the required disk image.

Optionally can setup the type of server, zone to locate it, groups to join and custom metadata.

Parameters

Allowed Account states

This action can only be performed when the owning Account is in the following states:

• active
• overdue
• warning
• closed

Get request

Get full details of the server.

Parameters

This action does not have any parameters.

Allowed Account states

This action can only be performed when the owning Account is in the following states:

• active
• overdue
• warning
• suspended
• closed

Update request

Update some details of the server.

Parameters

Allowed Account states

This action can only be performed when the owning Account is in the following states:

• active
• overdue
• warning
• closed

Delete request

Destroy the server and free up the resources.

Parameters

This action does not have any parameters.

Allowed Account states

This action can only be performed when the owning Account is in the following states:

• active
• overdue
• warning
• suspended
• closed

Start request

Will issue a start request for the server to become active.

Parameters

This action does not have any parameters.

Allowed Account states

This action can only be performed when the owning Account is in the following states:

• active
• overdue
• warning
• closed

Stop request

Will issue a stop request for the server to become inactive.

Parameters

This action does not have any parameters.

Allowed Account states

This action can only be performed when the owning Account is in the following states:

• active
• overdue
• warning
• suspended
• closed

Reboot request

Issues a ‘soft’ reboot to the server however the OS may ignore it. The console remains connected.

Parameters

This action does not have any parameters.

Allowed Account states

This action can only be performed when the owning Account is in the following states:

• active
• overdue
• warning
• suspended
• closed

Reset request

Issues a ‘hard’ reboot request to the server which can not be ignored by the OS. The console remains connected.

Parameters

This action does not have any parameters.

Allowed Account states

This action can only be performed when the owning Account is in the following states:

• active
• overdue
• warning
• suspended
• closed

Shutdown request

Will issue a safe shutdown request for the server.

Parameters

This action does not have any parameters.

Allowed Account states

This action can only be performed when the owning Account is in the following states:

• active
• overdue
• warning
• suspended
• closed

Activate console request

Enable console access via VNC to the server for 15 minutes.

Parameters

This action does not have any parameters.

Allowed Account states

This action can only be performed when the owning Account is in the following states:

• active
• overdue
• warning
• closed

Snapshot request

Will issue a request to snapshot the Server

Parameters

This action does not have any parameters.

Allowed Account states

This action can only be performed when the owning Account is in the following states:

• active
• overdue
• warning
• closed

Lock resource request

Parameters

This action does not have any parameters.

Allowed Account states

This action can only be performed when the owning Account is in the following states:

• active
• overdue
• warning
• closed

Unlock resource request

Parameters

This action does not have any parameters.

Allowed Account states

This action can only be performed when the owning Account is in the following states:

• active
• overdue
• warning
• closed

Server group

A grouping of Servers

Attributes

Links

Representations

Full Server group representation example

{"id": "grp-sda44",
 "resource_type": "server_group",
 "url": "https://api.gb1.brightbox.com/1.0/server_groups/grp-sda44",
 "name": "default",
 "description": null,
 "created_at": "2011-10-01T00:00:00Z",
 "default": true,
 "fqdn": "grp-sda44.gb1.brightbox.com",
 "account":
  {"id": "acc-43ks4",
   "resource_type": "account",
   "url": "https://api.gb1.brightbox.com/1.0/accounts/acc-43ks4",
   "name": "Brightbox",
   "status": "active"},
 "firewall_policy":
  {"id": "fwp-j3654",
   "resource_type": "firewall_policy",
   "url": "https://api.gb1.brightbox.com/1.0/firewall_policies/fwp-j3654",
   "default": true,
   "name": "default",
   "created_at": "2011-10-01T00:00:00Z",
   "description": null},
 "servers":
  [{"id": "srv-lv426",
    "resource_type": "server",
    "url": "https://api.gb1.brightbox.com/1.0/servers/srv-lv426",
    "name": "",
    "status": "active",
    "locked": false,
    "hostname": "srv-lv426",
    "fqdn": "srv-lv426.gb1.brightbox.com",
    "created_at": "2011-10-01T01:00:00Z",
    "started_at": "2011-10-01T01:01:00Z",
    "deleted_at": null}]}

Collection Server group representation example

[{"id": "grp-sda44",
  "resource_type": "server_group",
  "url": "https://api.gb1.brightbox.com/1.0/server_groups/grp-sda44",
  "name": "default",
  "description": null,
  "created_at": "2011-10-01T00:00:00Z",
  "default": true,
  "fqdn": "grp-sda44.gb1.brightbox.com",
  "account":
   {"id": "acc-43ks4",
    "resource_type": "account",
    "url": "https://api.gb1.brightbox.com/1.0/accounts/acc-43ks4",
    "name": "Brightbox",
    "status": "active"},
  "firewall_policy":
   {"id": "fwp-j3654",
    "resource_type": "firewall_policy",
    "url": "https://api.gb1.brightbox.com/1.0/firewall_policies/fwp-j3654",
    "default": true,
    "name": "default",
    "created_at": "2011-10-01T00:00:00Z",
    "description": null},
  "servers":
   [{"id": "srv-lv426",
     "resource_type": "server",
     "url": "https://api.gb1.brightbox.com/1.0/servers/srv-lv426",
     "name": "",
     "status": "active",
     "locked": false,
     "hostname": "srv-lv426",
     "fqdn": "srv-lv426.gb1.brightbox.com",
     "created_at": "2011-10-01T01:00:00Z",
     "started_at": "2011-10-01T01:01:00Z",
     "deleted_at": null}]}]

Nested Server group representation example

{"id": "grp-sda44",
 "resource_type": "server_group",
 "url": "https://api.gb1.brightbox.com/1.0/server_groups/grp-sda44",
 "name": "default",
 "description": null,
 "created_at": "2011-10-01T00:00:00Z",
 "default": true,
 "fqdn": "grp-sda44.gb1.brightbox.com"}

Actions

List request

Lists summary details of server groups owned by the account.

Parameters

This action does not have any parameters.

Allowed Account states

This action can only be performed when the owning Account is in the following states:

• active
• overdue
• warning
• suspended
• closed

Create request

Create a new server group for the account.

Parameters

Allowed Account states

This action can only be performed when the owning Account is in the following states:

• active
• overdue
• warning
• closed

Get request

Get details of the server group.

Parameters

This action does not have any parameters.

Allowed Account states

This action can only be performed when the owning Account is in the following states:

• active
• overdue
• warning
• suspended
• closed

Update request

Update some details of the server group.

Parameters

Allowed Account states

This action can only be performed when the owning Account is in the following states:

• active
• overdue
• warning
• closed

Add servers request

Add a number of servers to the server group.

Parameters

Allowed Account states

This action can only be performed when the owning Account is in the following states:

• active
• overdue
• warning
• closed

Remove servers request

Remove a number of servers from the server group.

Parameters

Allowed Account states

This action can only be performed when the owning Account is in the following states:

• active
• overdue
• warning
• closed

Move servers request

Removes a number of server from the server group and adds them to another server group given in parameters.

Parameters

Allowed Account states

This action can only be performed when the owning Account is in the following states:

• active
• overdue
• warning
• closed

Delete request

Destroy the server group if not in use.

Parameters

This action does not have any parameters.

Allowed Account states

This action can only be performed when the owning Account is in the following states:

• active
• overdue
• warning
• closed

Server type

ServerType represents what we might currently call a product. All servers are created with a server type, which describes it’s configuration.

States

Attributes

Representations

Full Server type representation example

{"id": "typ-zx45f",
 "resource_type": "server_type",
 "url": "https://api.gb1.brightbox.com/1.0/server_types/typ-zx45f",
 "name": "Small",
 "status": "available",
 "cores": 2,
 "ram": 2048,
 "disk_size": 81920,
 "handle": "small"}

Collection Server type representation example

[{"id": "typ-zx45f",
  "resource_type": "server_type",
  "url": "https://api.gb1.brightbox.com/1.0/server_types/typ-zx45f",
  "name": "Small",
  "status": "available",
  "cores": 2,
  "ram": 2048,
  "disk_size": 81920,
  "handle": "small"}]

Nested Server type representation example

{"id": "typ-zx45f",
 "resource_type": "server_type",
 "url": "https://api.gb1.brightbox.com/1.0/server_types/typ-zx45f",
 "name": "Small",
 "status": "available",
 "cores": 2,
 "ram": 2048,
 "disk_size": 81920,
 "handle": "small"}

Actions

List request

Lists summary details of server types available to the account.

Parameters

This action does not have any parameters.

Get request

Get full details of the server type.

Parameters

This action does not have any parameters.

User

Customers interact with Brightbox by creating a User (also known as "registering") on the Brightbox system and then logging in using their credentials (email,password). A user may have access to many Accounts, whether as the Owner or with limited permissions.

Attributes

Links

Representations

Full User representation example

{"id": "usr-kl435",
 "resource_type": "user",
 "url": "https://api.gb1.brightbox.com/1.0/users/usr-kl435",
 "name": "John Jarvis",
 "email_address": "jjarvis@example.com",
 "email_verified": true,
 "ssh_key": "",
 "messaging_pref": true,
 "created_at": null,
 "2fa":
  {"enabled": false},
 "default_account":
  {"id": "acc-43ks4",
   "resource_type": "account",
   "url": "https://api.gb1.brightbox.com/1.0/accounts/acc-43ks4",
   "name": "Brightbox",
   "status": "active"},
 "accounts":
  [{"id": "acc-43ks4",
    "resource_type": "account",
    "url": "https://api.gb1.brightbox.com/1.0/accounts/acc-43ks4",
    "name": "Brightbox",
    "status": "active"}]}

Collection User representation example

[{"id": "usr-kl435",
  "resource_type": "user",
  "url": "https://api.gb1.brightbox.com/1.0/users/usr-kl435",
  "name": "John Jarvis",
  "email_address": "jjarvis@example.com",
  "email_verified": true,
  "2fa":
   {"enabled": false},
  "default_account":
   {"id": "acc-43ks4",
    "resource_type": "account",
    "url": "https://api.gb1.brightbox.com/1.0/accounts/acc-43ks4",
    "name": "Brightbox",
    "status": "active"},
  "accounts":
   [{"id": "acc-43ks4",
     "resource_type": "account",
     "url": "https://api.gb1.brightbox.com/1.0/accounts/acc-43ks4",
     "name": "Brightbox",
     "status": "active"}]}]

Nested User representation example

{"id": "usr-kl435",
 "resource_type": "user",
 "url": "https://api.gb1.brightbox.com/1.0/users/usr-kl435",
 "name": "John Jarvis",
 "email_address": "jjarvis@example.com",
 "2fa":
  {"enabled": false}}

Actions

List request

Lists summary details of user.

Parameters

This action does not have any parameters.

Get request

Get full details of the user.

Parameters

This action does not have any parameters.

Update request

Update some details of your user profile.

Parameters

User collaboration

A collaboration forms the link between an Account and a User, giving the User access to the specified Account. User collaborations allow you to list and interact with Collaborations that the specified user has.

States

Attributes

Links

Representations

Full User collaboration representation example

{"id": null,
 "resource_type": "collaboration",
 "url": "https://api.gb1.brightbox.com/1.0/user/collaborations/",
 "status": "pending",
 "email": "jjarvis@example.com",
 "role": "admin",
 "created_at": null,
 "started_at": null,
 "finished_at": null,
 "role_label": "Collaborator",
 "user": null,
 "account":
  {"id": "acc-43ks4",
   "resource_type": "account",
   "url": "https://api.gb1.brightbox.com/1.0/accounts/acc-43ks4",
   "name": "Brightbox",
   "status": "active"},
 "inviter":
  {"id": "usr-e8t4w",
   "resource_type": "user",
   "url": "https://api.gb1.brightbox.com/1.0/users/usr-e8t4w",
   "name": "Tom Clock",
   "email_address": "tclock@example.com",
   "2fa":
    {"enabled": false}}}

Collection User collaboration representation example

[{"id": null,
  "resource_type": "collaboration",
  "url": "https://api.gb1.brightbox.com/1.0/user/collaborations/",
  "status": "pending",
  "email": "jjarvis@example.com",
  "role": "admin",
  "created_at": null,
  "started_at": null,
  "finished_at": null,
  "role_label": "Collaborator",
  "user": null,
  "account":
   {"id": "acc-43ks4",
    "resource_type": "account",
    "url": "https://api.gb1.brightbox.com/1.0/accounts/acc-43ks4",
    "name": "Brightbox",
    "status": "active"},
  "inviter":
   {"id": "usr-e8t4w",
    "resource_type": "user",
    "url": "https://api.gb1.brightbox.com/1.0/users/usr-e8t4w",
    "name": "Tom Clock",
    "email_address": "tclock@example.com",
    "2fa":
     {"enabled": false}}}]

Nested User collaboration representation example

{"id": null,
 "resource_type": "collaboration",
 "url": "https://api.gb1.brightbox.com/1.0/user/collaborations/",
 "status": "pending",
 "email": "jjarvis@example.com",
 "role": "admin",
 "created_at": null,
 "started_at": null,
 "finished_at": null,
 "role_label": "Collaborator"}

Actions

List request

Lists all collaborations the user is involved with

Parameters

This action does not have any parameters.

Get request

Shows details of the specified collaboration

Parameters

This action does not have any parameters.

Accept request

Accepts the collaboration giving access to the account

Parameters

This action does not have any parameters.

Reject request

Rejects the collaboration

Parameters

This action does not have any parameters.

Delete request

Ends an existing ‘accepted’ collaboration

Parameters

This action does not have any parameters.

Zone

A Zone represents cloud resources at a datacentre. Each Zone is completely isolated in terms of power, cooling, security and networking equipment.

Attributes

Representations

Full Zone representation example

{"id": "zon-328ds",
 "resource_type": "zone",
 "url": "https://api.gb1.brightbox.com/1.0/zones/zon-328ds",
 "handle": "gb1"}

Collection Zone representation example

[{"id": "zon-328ds",
  "resource_type": "zone",
  "url": "https://api.gb1.brightbox.com/1.0/zones/zon-328ds",
  "handle": "gb1"}]

Nested Zone representation example

{"id": "zon-328ds",
 "resource_type": "zone",
 "url": "https://api.gb1.brightbox.com/1.0/zones/zon-328ds",
 "handle": "gb1"}

Actions

List request

Lists summary details of zones available to the account.

Parameters

This action does not have any parameters.

Allowed Account states

This action can only be performed when the owning Account is in the following states:

• pending
• active
• overdue
• warning
• suspended
• closed

Get request

Get full details of the zone.

Parameters

This action does not have any parameters.

Allowed Account states

This action can only be performed when the owning Account is in the following states:

• pending
• active
• overdue
• warning
• suspended
• closed

Errors

There are two different styles of errors that the API may return depending on where the problem with the request occurred.

Authentication or access control errors use the OAuth2.0 format. This format provides a single error name and a description.

A single request may contain multiple errors so all errors relating to the API itself will return an error name and an array of errors.

Authentication errors

Requests related to authentication or authorization are implemented as specified in the OAuth2.0 specification.

  HTTP/1.1 400 Bad Request
  WWW-Authenticate: OAuth error="invalid_request"

  {
    "error": "invalid_request",
    "error_description": "The request is missing a required parameter, includes an unsupported parameter or parameter value, or is otherwise malformed."
  }

As per the specification there is also a "WWW-Authenticate" header that contains the error name as well.

Request errors

When an error occurs for GET or POST requests, the content body includes a JSON object containing details of the error for the client to handle.

  {
      "error_name": "Forbidden",
      "errors": [
          "Account limit reached, please contact support for more information"
      ]
  }

API Errors include more detailed messages where possible without giving out information to unprivileged users.