Skip to content
Last updated

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).
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.