Security

Authentication

Digital Platform APIs require an authentication token to be provided in each request via the Authorization HTTP header. Missing, expired, or invalid tokens will result in a 401: Unauthorized response.

  • Bearer authentication tokens are obtained from the Vista Global Authentication Service (GAS).
Copy
Copied
curl 'https://auth.sandbox.vista.co/connect/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=password' \
--data-urlencode 'client_id={{textual-description-of-the-application}}}' \
--data-urlencode 'username={{username}}' \
--data-urlencode 'password={{password}}'

{"token_type":"Bearer","access_token":"eyJhbGciOiJSUzI... [truncated for brevity]","expires_in":43200}
  • Credentials ( username and password ) for the Global Authentication Service are provided by your Vista services representative.
  • Credentials should be treated as sensitive and stored securely and never exposed to unauthorised personnel.
  • Browser and mobile-based clients should NEVER have access to these credentials, ans should instead rely on secure server-side services to provide tokens. However, the access_token returned from the response of this call IS safe to make available to public facing clients.
  • GAS tokens ( access_token ) are long-lived with an expiry of 12 hours.
  • GAS tokens should be cached centrally and re-used, not generated per-request or per-browser session.
  • GAS tokens should be pro-actively refreshed before expiry to prevent 401: Unauthorized responses.

Authorisation

  • There are several mechanisms that provide authorisation for API requests. Any request that violates authorisation configuration results in a 403: Forbidden response.
  • Security configuration controlling authorisation for your system is performed by your Vista account representative.

Google reCAPTCHA v2

Some endpoints, like Loyalty Authentication, require a Google reCAPTCHA v2 challenge to be fulfilled to successfully call the endpoint. This is required to protect the system from attacks like credential stuffing. For such endpoints, a reCAPTCHA challenge response should be included in the CaptchaResponse HTTP header property of the request. Details on how to retrieve a reCAPTCHA challenge response can be found in the Google reCATPCHA v2 documentation.

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

Licensing

Certain API actions/endpoints may also validate licenses assigned to the requesting GAS user. Assigning licenses to an organisation is performed by your Vista services representative.