VSA 10 API guide
NAVIGATION Administration > Configuration > API Access
SECURITY Administrator access to VSA 10
VSA 10 provides an API layer for general third-party integrations and an enhanced framework for TAP-approved trusted applications, which includes Kaseya products. The API is based on REST principles and OData best practices. Endpoint response properties are standardized using the PascalCase naming convention, and return lists use OData and support paging, filtering, and sorting.
The API is one part of a Complete Integration Framework and includes the following:
- Secure token-based access with implicit and explicit trust.
- A robust set of API endpoints with a defined roadmap that supports common integration use cases.
API documentation
• Public API documentation: https://api.vsax.net
• While logged in to your VSA 10 instance, API documentation can be found at your server domain followed by the path /api (for example: https://exampleserver.vsax.net/api).
The documentation contains detailed information about: (1) API endpoints and includes (2) examples of usage and return data using common scripting and programming languages, such as PowerShell, cURL, Python, Node.js, PHP, C#, and Java.
API access
The VSA 10 API uses basic authentication for all requests and requires a token for access.
NOTE All requests must be made via HTTPS; otherwise, the request will fail. Basic authentication requires an authorization header with the token ID and token secret in the TOKEN_ID:TOKEN_SECRET format encoded as Base64.
VSA 10 API endpoints are secured using token-based access controls and can be accessed only once a token has been created and authorized for use.
Token-based API access allows technicians to grant explicitly controlled authorization tokens for a more secure API-only access entity that is distinctly separate from user accounts while also consolidating the management of API access controls.
From the tabs on the API Access page, two methods of API access authorization can be used to access VSA 10 APIs:
Trusted Applications
This is reserved exclusively for access by other Kaseya products and trusted third-party vendors.
Trusted applications allow for a simple OAuth-based authorization process to be used to establish and enable an integration with VSA 10 and a specific application (for example, products that are part of Kaseya’s IT Complete product suite).
NOTE Trusted applications are predefined and established by the product teams. A customer authorizes a trusted application during the configuration of its integration with VSA 10. This process eliminates the need to manually create API access credentials.
Third-Party Tokens
This is the method of access a typical customer would use to programmatically interact with VSA 10.
Third-party tokens allow for the creation of a unique API token that requires explicit trust configurations for controlling when, what, and from where the token is authorized for use with respect to the API. Once the token is generated, the token ID and token secret would be used to gain access to the API and its use would be restricted based on any individual authorization controls defined.
Creating third-party tokens
To create a third-party token, from the left navigation menu, navigate to Configuration > API Access > Third-Party Tokens and click Create Token in the upper-right corner of the page.
To increase security, third-party tokens support the configuration of start dates and expiration dates, whitelisted IP addresses for granular access restrictions, and granular controls for access to specific organizations and individual API endpoints.
To select exact API permissions, click Edit Permissions in the Permissions section in the Authorization tab.
When finished configuring the token, click Create to generate the token.
Revoking third-party tokens
Tokens can be revoked to immediately prohibit further use. To do so, click the Revoke Token icon 
in the respective row in the Third-Party Tokens tab on the API Access page, or click the Revoke button in the Details tab when editing a token.
By revoking an existing third-party token, you will have 30 days until it is automatically deleted. To reinstate the token, simply regenerate the token secret prior to end of the 30-day period using the Regenerate Token Secret option in the Details tab when editing a token.
API rate limits
An initiative is underway to increase rate limits to a new standard frequency across all existing and new API endpoints, where possible. These changes should be completed and in product by Q3 2024 and will include a new API endpoint to get existing rate limit information.
NOTE Until the time rates are standardized and increased, currently, there are some variations in limits.
Most existing endpoints support 3,600 requests per hour, while other endpoints are more limited, as follows:
- Get Assets and Get Assets for a Specific Device currently support 60 requests per hour.
- Notify currently supports 10 requests per 5 seconds, 50 requests per minute, 200 requests per 5 minutes, 500 requests per hour, and 2,000 requests per day.
- Get a Group Package is limited to 60 requests per hour (this limit exists because this endpoint generates a new package for download in real time).
API failed requests
Limits are in place for failed API requests per IP address.
As follows are the current API failed request limits, which will be changing to new limits in Q3 2024:
- 30 requests per minute, after which the IP address will be blocked for up to 1 minute.
- 100 requests per 5 minutes, after which the IP address will be blocked for up to 5 minutes.
- 300 requests per hour, after which the IP address will be blocked for up to 1 hour.
- 1,000 requests per day, after which the IP address will be blocked for up to 24 hours.
EXAMPLE As an example, from the same IP address, 30 requests failed in a minute (as in attempting to access a non-existent organization 30 times), the specific IP address will be blocked from making any other requests for one minute.
In Q3 2024, the preceding limits will be deprecated and replaced by the following:
- 100 requests per minute, after which the IP address will be blocked for up to 1 minute.
- 2,000 requests per hour, after which the IP address will be blocked for up to 1 hour.
API errors
The VSA 10 API uses conventional HTTP response codes to indicate success or failure of an API request. In general, the following is true:
- Codes in the 2xx range indicate success.
- Codes in the 4xx range indicate a validation error that resulted from provided information (for example, a required parameter was missing, invalid characters were used, and so forth).
- Codes in the 5xx range indicate an error with the VSA 10 servers.
| Error code | Meaning |
|---|---|
| 200 | OK |
| 400 | Bad Request |
| 401 | Unauthorized |
| 403 | Request Failed |
| 404 | Not Found |
| 500 | Internal Error |
| 502 | Internal Error |
| 503 | Internal Error |
| 504 | Internal Errors |
