Xibo Platform API


#1

Spring Signage provide an API (application program interface) for integrating the Xibo Platform into your own website or systems. The API can be used to query for details about your account, licence or cloud usage and make changes, such as provisioning a new CMS instance.

This is not the Xibo CMS API, details for which can be found in the manual.

We have made the API available to all customers holding a valid reseller account subscription. Reseller subscriptions are usually annual and the API keys are only valid while the subscription is active.

The Xibo Platform API is a REST API designed to have intuitively named resource locations, JSON responses and HTTP response codes to indicate status. All requests must be made over HTTPS and HTTP requests will fail.

There is a live and test environment.

A library written for PHP is available and simplifies interaction with the API. Further information regarding the library, install and usage can be found in the GitHub repository.

Managing API Access

Before using the Xibo Platform API you will need to understand how the API fits into your springsignage.com reseller account, how we make sure no-one is able to gain access to your account through the API and how you can test your integration in a safe way.

We will cover the following things:

  • Live mode and testing
  • API Keys
  • Billing

Live mode and testing

There are two separate environments for things you want to happen “for real” and things you are still testing. All API requests exist in either the live or test environment and they don’t mix together. There is a separate address and set of API keys for each environment.

Transactions that happen in the live environment will effect your live account and therefore effect your customers and/or billing. For example if you create a new order for a CMS instance in the live environment, your account will be charged and the CMS instance created - the exact same transaction in the test environment would only “pretend” to create the CMS and charge your account.

API Keys

Your API keys are stored securely in your account and can be “refreshed” at any time if you think someone else may have copied them. When you first open an account the clientId and clientSecret will be empty and you will need to provide a name for your integration and click save to get both keys.

We strongly recommend that both keys remain secret, but at the least the clientSecret must be private at all times.

To enable your integration and get your API keys please visit the “My Account” -> Security section of the customer portal (remember to use the test one first) and name your integration - see below for an example.

Billing

In many cases the goal of integration is to minimise or eliminate manual actions, therefore it is often desirable for you to automate payment of orders, which is done by saving your card details in your account. Monthly billing of CMS instances require a saved card, for other orders it is optional and we will email you an invoice with payment link instead.

You will find the option to save a card on the Billing tab of “My Account”, shown below:

Please note, Spring Signage do not actually store your card details. These are stored by our payment processor (stripe.com).

Authentication

The Spring Signage API uses an oAuth2 Authorization Server with Client Credential Grant in order to Authenticate requests to the API. Client Credentials are available from the My Account section of the Web UI and should be kept secret.

The Client Credentials are exchanged with the Authorization Server for an access_token, this is done using a POST request to the access_token endpoint.

https://xibo.org.uk/authorize/access_token
     
POST
grant_type=client_credentials
client_id=<your client id>
client_secret=<your client secret>

The response will contain an access token for use with the current session and an expiry time which you can use to determine when you will need to request another access token.

{
  "access_token": "T6dqCj3rZ24TeG73nzykrMKJwsiRsqfdlO1zC66a",
  "token_type": "Bearer",
  "expires_in": 3600
}

The access_token is used for all other requests to the Resource Server and can be send as a HTTP Authorization header or appended to the API URL as shown below.

https://xibo.org.uk/authorize?access_token=<<access_token>>

Resource Server

All further API calls are secured behind the resource server via the URL:

https://xibo.org.uk/api

The above URL is known as the “home” location and will output the following in a successful request:

{
  "title": "Xibo Platform API"
}

All responses will have a HTTP status of either 200 or 500 (success or failure), with the same code embedded in the JSON response. Errors will have an additional “message” parameter providing a human readable error message.

Checkout and Ordering

The most common use case for the API is linking to a 3rd party e-commerce system and ordering products through the API. This is discussed in a separate article: Checkout and Ordering through the API.

We have a pre-built WooCommerce plugin available for purchase, see: WooCommerce Plugin for the Xibo Platform


Introduction / Table of Contents