# Security

These security details are relevant for both standard, custom APIs, and Dynamic Data API.

## 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:

```bash
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](#obtaining-a-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

```bash
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](https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.4). 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](/integration-platform/getting-started/example-queries#obtaining-a-partner-account-token).

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