Cyberwatch API usage
Cyberwatch users have access to an API that allows them to interact with most of the resources visible in the application. This access can, for example, allow the automation of certain tasks or the fetching of personalized results…
This page is an introduction to the operation and usage of this API.
Interacting with the Cyberwatch API
As the Cyberwatch API returns responses in JSON format, it can be queried by using a curl client, the PowerShell Invoke-WebRequest cmdlet, or our Python client.
Authenticate to the API and test your connection
Usage of the API, regardless of the queried route, requires authentication using API keys of a Cyberwatch user with an Administrator role. These API keys can be generated from the Cyberwatch GUI, in Profile > API Keys tab, for each user.
These credentials can be used through the two proposed authentication modes: basic-auth and apiAuth. We document the usage of curl, the PowerShell Invoke-WebRequest cmdlet, or our Python API client.
In our documentation and examples, we use basic-auth, but more information about apiAuth is available here.
Test your connection
The commands referenced below allow you to test the validity of the used credentials and test the communication to your Cyberwatch API. If it works, it returns a user id.
This query only requires an API keys with read-only rights. It may therefore be necessary to check the access level of the keys used, depending on future requests.
Attached are detailed examples of how to run this login test using curl, the PowerShell Invoke-WebRequest cmdlet, or our Python API client.
Diagnose connection problems
You encounter a 401 error
A 401 error means authentication failed. To fix this, you will first need to check that the keys entered are correct. Secondly, you should check that the URL matches the Cyberwatch instance desired.You encounter a 403 error
When this error occurs, it is caused by a privilege issue. The API keys may have been generated with an account that does not have administrator rights. Another possible case is that the keys do not have access to the API, for example, those for installing agents. To check these elements, you will need to go to the Cyberwatch application web interface. Once logged in, go to the “My Profile” page. The “Role” field corresponds to the level privilege of your account. To use the API, the latter must be "Administrator". Then go to the bottom of the page, then “View my API keys”. You will then have details of the API keys linked to your account, as well as their level of rights. For the sole purpose of retrieving data from the API, "Read only" mode will suffice. Otherwise, the key must have the "Full" access level.API endpoints and responses
The different endpoints of the API can be consulted from a Swagger documentation accessible from your application, by clicking on the </> button in the top right corner of the page.
From Swagger, each section describes the route used, as well as the list of available parameters and an example of the data structure returned by the query. It is also possible to generate this list in OpenAPI format from here, to import it into other tools like Postman.
Swagger also allows you to generate authenticated curl requests and execute them directly, in order to test API returns of your instance.
As with all API requests, Swagger requires authentication using API credentials as described previously. We recommend you to configure them directly via Swagger’s “Authentication” form. When the credentials are provided in this way Swagger generates the curl authentication header, which makes the command easily reusable.
Deprecated API clients
Since Cyberwatch version 13.0, our older, less permissive PowerShell and Python API clients have been deprecated.
If you have any questions on this topic, or if you need any help migrating an API script from a previous version to the new one, you can contact us by e-mail at support@cyberwatch.com, or by phone at +33 1 84 80 88 84.