Skip to content
Last updated

Security

These security details are relevant for both standard and custom APIs.

Authentication

Integration Platform APIs require following three security headers:

  • Vista-Api-Key
  • Vista-Api-Tenant (not required for custom APIs)
  • Bearer JWT token in the Authorization HTTP header.
NOTE

Missing, expired or invalid header values will result in a 401: Unauthorized response.

API calls

An example API call to our APIs using curl will look like:

curl --location 'https://integration.app.vista.co/api/...' \
--header 'Content-Type: application/json' \
--header 'CorrelationId: my-correlation-id' \
--header 'Vista-Api-Key: <VISTA API KEY>' \
--header 'Vista-Api-Tenant: <VISTA API KEY TENANT>' \
--header 'Authorization: Bearer <VISTA JWT>' \
...

Obtaining authentication details

Security credentials and details are provided by your Vista services representative, including:

  • Credentials
    • Client ID
    • Client Secret
    • Vista Tenant Code (also used for Vista-Api-Tenant)
    • Vista-Api-Key
  • Additional information for requesting JWT:
    • The identity management service hostname for the environment.
    • The type of the JWT token to use, Partner Account Token is the only token type we officially support at the moment.
NOTE

While Vista-Api-Key and Vista-Api-Tenant can be considered static, JWT tokens need to be programmatically requested and renewed periodically using the client ID, secret and tenant code.

Obtaining a partner account token

A partner account JWT can be obtained using following authentication details:

  • Client ID
  • Client Secret
  • Vista Tenant Code

Request for obtaining a partner account token looks like

curl --location 'https://<IDENTITY SERVICE HOSTNAME>/oauth/token' \
--header 'Content-Type: application/json' \
--data '{
  "client_id": "<CLIENT ID>",
  "grant_type": "client_credentials",
  "client_secret": "<CLIENT SECRET>",
  "audience": "https://partner.vista.co/",
  "tenant_code": "<VISTA TENANT CODE>"
}'
IMPORTANT

The /oauth/token API endpoint has low rate limits: 25 tokens per Client ID per 15 minutes window for live environments, lower for sandbox environments. If you exceed this limit, you will receive the following error:

400 - The account has exhausted allocated token requests.

A partner account JWT remains valid for a relatively long period and should therefore be cached and reused for as long as possible.

The correct way to determine if a JWT can be reused is to decode the token and check its exp - Expiration Time claim. This value represents the number of seconds since 1970-01-01T00:00:00Z UTC.

You should only request a new JWT when the cached JWT is close to its expiration time, allowing some leeway to account for clock skew.

More detailed examples can be found at example queries.

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.