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.

Authentication

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 are available here.

Authenticate to the API and 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 an user id.

N.B 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.

Returned structures and API queries

The different access points of the API can be consulted from a Swagger documentation accessible from your application, by clicking on the </> button on 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, in order 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 “Authorize” button. When the credentials are provided in this way Swagger generates the curl authentication header, which makes the command easily reusable.

API clients support

Our former API documentation, as well as our former, less permissive PowerShell, and Python API clients, are therefore deprecated.

These documentations are respectively replaced by our API documentations for curl, PowerShell, and Python.

If you have any question on this topic, or if you need any help to migrate an API script from a previous version to the new one, you can contact us by e-mail at support@cyberwatch.fr, or by phone at +33 1 84 80 88 84.