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:

Copy
Copied
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 token can be obtained using following authentication details:

  • Client ID
  • Client Secret
  • Vista Tenant Code

Request for obtaining a partner account token looks like

Copy
Copied
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>"
}'

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.