Connect API - version 5.0.9.24 - 7e0560eca05bb0f97d04d090565b2aa195fd9502

Security

In order to communicate with Connect, clients need to be aware of the security settings of their Connect environment.

Connect API tokens

All endpoints, except for a few diagnostic/metadata endpoints such as the Health and Version endpoints, require a Connect API token to be included in the connectApiToken HTTP header property. These tokens are created and managed by the administrators of the Connect deployment, and will associate the calling application with a specific Vista Client. Each Client may have access to a specific set of endpoints, security behaviours, and data within the API. Please consult with your Connect administrator to find out what permissions/behaviours have been set in order avoid potential confusion during development.

Endpoints will return an HTTP 401 response if the provided Connect API token is not a valid token.

Client permissions and behaviours

Depending on the configured security settings, some clients may have access to endpoints while others don't, and some clients may be able to perform certain actions using those endpoints while others can't.

For example, refunding a booking may be available on call centre and mobile applications, but not available on your ticketing website. So security would be configured to allow the call centre and mobile clients access to the refund endpoint, but not for the website client. Additionally, the call centre client may be able to refund any booking, while the mobile client can only refund bookings made by the currently authenticated Loyalty member (as defined by the current Loyalty Session token).

Endpoints will return an HTTP 403 response if the provided Connect API token is valid but is not authorised to access the requested endpoint/functionality.

HMAC authentication

Since certain client applications will need to communicate with Connect directly (such as mobile applications) their Connect API token will be publicly accessible. To help provide extra security in these situations, HMAC authentication may be enabled by Connect administrators. If HMAC is enabled in your environment, details on how to form the required headers can be found in the Securing Connect HowTo Guide.

Endpoints will return an HTTP 401 response if HMAC authentication is enabled and valid HMAC parameters are not provided.

reCAPTCHA v2

Most Connect endpoints can be optionally protected from automated requests via the use of reCAPTCHA v2. If reCAPTCHA v2 is enabled your client should retrieve a reCAPTCHA challenge response and pass it to Connect in the CaptchaResponse HTTP header property. Details on how to retrieve a reCAPTCHA challenge response can be found on Google's documentation.

Endpoints will return an HTTP 403 response if a valid CAPTCHA response is not provided when reCAPTCHA is enabled.

Depending on Connect configuration, endpoints may return an HTTP 400 response if a CAPTCHA response is provided to an endpoint that does not have reCAPTCHA enabled.

Rate limiting

Connect will enforce rate limits on certain endpoints that could return sensitive information if subjected to repeated requests. Rate limiting reducues the risk, for example, of a malicious party obtaining a gift-card PIN by repeatedly making requests to the gift-card balance endpoint.

When the rate limit is exceeded these endpoints will return an HTTP 429 response with the following response body indicating when requests will be allowed again:

{
  "blockedUntilUtc": "2021-01-21T04:02:20.360Z"
}

The API reference pages will list 429 as a possible status code when rate limiting can be enabled on a given endpoint. The endpoints, and the specific endpoint parameters, that may be rate limited are as follows:

Details on how to configure rate limiting can be found in the Securing Connect HowTo Guide.