Authentication

All endpoints that create, update, or delete records as well as endpoints that allow reading sensitive methods require authentication. If no authentication is provided, the request will error with a 401 un-authorized status code. Authorization can be provided in two ways, described below.

Bearer Token Authentication

The Carousel API will authenticate requests that contain a Bearer Token linking the request to an active OAuth2 access token. The Carousel UI generates a Bearer token when you log in with your email and password, but that flow is generally reserved for the UI. For direct API access, you should use API Key Authentication to avoid having your integrations break if someone changes their password or leaves the company.

HTTP Basic Authentication

Historically, the Carousel API allowed basic authentication for accessing the API, this method is now deprecated and should no longer be used.

API Key Authentication

As a preferred alternative to username and password credentials, you can authenticate using an API key. API keys are created by a Site Administrator in the Carousel settings. When you create an API key, you receive a Key (public identifier) and a Secret (shown only once at creation).

To authenticate with an API key, use the same OAuth token endpoint (/v1/auth/token) but provide the API key as the username and the secret as the password:

POST /CarouselAPI/v1/auth/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id=YOUR_API_KEY&client_secret=YOUR_API_SECRET
        

The response will contain a bearer token that you use in the Authorization header for subsequent requests. The token can be refreshed, but the typical workflow for an integration would be to fetch a bearer token from the API Key when it starts, use the token for that session, then get a new one the next time it runs.

Overview

Media Types

The Carousel API supports the application/json media type, and all requests with the exception of requests made to /auth should contain an Accepts: application/json header. When performing a POST or PUT request, a Content-Type: application/json should also be sent.

All requests made to /auth should contain an Accepts: application/json header. When performing a POST or PUT request, a Content-Type: application/x-www-form-urlencoded should also be sent.

Response Structure

All JSON responses will contain a root object that contains the object being returned. Similarly, all requests are expected to contain a root object. See the section on API Requests & Live Testing for more details on JSON payloads.

Required Data for Updates

All endpoints require the full model structure when updating records. The Carousel API does not support PATCH requests and values marked as 'optional' will be treated as falsey or not set if not included in the payload.

Getting All Zone Specific Content

Zone specific models like Bulletins, Media and Templates require you to specify a ZoneID as a query param in the GET request for performance reasons.

Creating and Updating Bulletins

Creating a Bulletin from a template

Because bulletins and templates share an almost identical content structure it is quite easy to use the properties of a template to create a new bulletin. You only need to add the additional scheduling and group information. Newly created bulletins will appear at the end of the list of bulletins on a player.

Bulletin Status

With the exception of the value Saved, all bulletins statuses are determined by the Carousel API based on settings like the bulletin's schedule, dynamic content, and the user's ability to publish content.

Bulletin Grouping

Every bulletin in Carousel is part of a group. When creating a new bulletin its important to create the group first and then create the bulletin with the GroupID properly referenced.

Bulletin (Group) Ordering

The OrderEntries endpoint is used to GET and PUT the order for groups and their bulletins. Since every bulletin is part of a group, the endpoint returns an array of group references and each group reference contains and array of bulletin IDs. The order of the items in each array is what determines the bulletin order for the zone and it must be put back in its entirety. The Order key is a read only value.

Partial Bulletin Records

For performance reasons, using the GET all bulletins endpoint returns a partial bulletin record that has a minimal set of data. These objects will have a PartialBulletin property set to True. It is important when retrieving a bulletin that you intended to make changes to, you must use the GET/{id} endpoint to retrieve a full record. Failure to retrieve and send the full bulletin record when updating can cause loss of data.

Cross Origin Resource Sharing (CORS)

The Carousel API is configured to allow Cross Origin Resource Sharing among all domains for read only GET requests. This will allow the Carousel API to be accessed via Javascript from modern web browsers. For more on CORS, see: https://developer.mozilla.org/en-US/docs/Web/HTTP/Access_control_CORS.

Versioning Compatibility

There are two version numbers when interacting with the Carousel API.

The first version number is the Carousel version number which can be obtained programmatically using the SystemInfo endpoint. This version number can be used to ensure that the Carousel server is compatible with the version required. It is recommended that clients confirm the Carousel version required when accessing the Carousel API.

The second version number is the Carousel API version which is currently v1. The Carousel API version will only be incremented if breaking changes are introduced to the API, meaning that an endpoint or model property has changed or been removed. Additions to the API, including new endpoints, models, or properties do not cause an increment in the API version. Therefore, it is important that clients be resilient to additional properties in request payloads. It is recommended to only rely on properties needed by the client application, not exact schemas.

When a breaking changed is introduced to the Carousel API, necessitating a new Carousel API version, the depreciated endpoints will still be made available for at least one Carousel release cycle. During this time, the depreciated endpoints will include an additional Warning header indicating the endpoint has been deprecated. It is recommended that clients monitor for the Warning header and alert users for the need to update the client.

Performance Considerations

For performance reasons certain API end points such as Media GET/, Bulletins GET/ and Templates GET/ require the user to specify a ZoneID query parameter when attempting to retrieve All items.

If no ZoneID query parameter is specified these requests will return a Unprocessable Entity (422) status code.

Testing

API Requests & Live Testing

The Carousel API comes with Swagger for testing the API. The Swagger interface can be found at /CarouselAPI/swagger. To test authenticated endpoints, use the Authorize button near the top of the interface, scroll down below where it says Bearer (OAuth2, clientCredentials) and enter a valid API Key key in the client_id field and secret into the client_secret field in the bottom section, then hit Authorize—alternatively you may enter a valid email in the username field and password in the top Bearer (OAuth2, password) section—then click the top Authorize to activate those credentials, but note the password flow will not be able to be used if the specified email has MFA enabled.