Accessing the VitalSigns API programatically

Introduction

Our API (Application Program Interface) capability provides you with full control to call PowerShell scripts from your existing software. The API is meant to integrate a high level of automation into your existing systems and workflows by leveraging the secure "sandbox" in which PowerShell scripts can be run as "PowerScripts. This enables you to

JSON based data notations make it easy to use our API from any programming language
RestFUL API so you don’t have to do any session management
Secure API requires OAuth "bearer" token to obtain access; the API cannot be misused by unauthorized users.

Since an API can be accessed by many different methods - JavaScript, PHP, Ruby, Python and so on - the documentation for most APIs doesn't tend to give specific instructions for how to connect and we will assume you have a basic understanding of calling APIs. We will instead give an overview of the process here.

Obtaining the API endpoint

The APIs are URLs which are appended to the hostname of the machine hosting VitalSigns. For instance if the machine hosting VitalSigns is usdopvsdev11svc.jnittech.com then the API call to get an authorization token would be http://usdopvsdev11svc.jnittech.com//token.

Other useful APIs include:

/token (a GET)

/services//get_powershell_scripts (a GET)

/services/execute_powershell_script (a POST)

Passing an OAuth Token to the API

All the VitalSigns APIs which do work require authentication in the form of an OAuth token. You can obtain this token by calling our /token API. You can still use the Authorization header with OAuth 2.0. There is a Bearer type specified in the Authorization header for use with OAuth bearer tokens (meaning the client app simply has to present ("bear") the token). The value of the header is the access token the client received from the Authorization Server. In the case of VitalSigns, the Authorization Server is the login process.

The token API is a POST request which take the username and password as parameters in the request payload

:

If successful the /token API will return back a token. You have to add this token to the header of any subsequent API requests which you make.

Important Tip

When you are first learning to use the API it is dramatically easier to use HTTP rather than HTTPS so you can see the plain text traffic but once you put it into production we highly recommend that you use SSL (https://).

There is a great tutorial explaining bearer tokens here → https://swagger.io/docs/specification/authentication/bearer-authentication/

For example.:

   GET /resource HTTP/1.1
   Host: server.example.com
   Authorization: Bearer mF_9.B5f-4.1JqM

Where mF_9.B5f-4.1JqM is your OAuth access token.

To make a request using curl

curl -H "Authorization: Token xxxxxxxxxxxxxx" https://www.example.com/

Learning How to Call a Specific Script with /services/get_powershell_scripts

The get_powershell_scripts API lists all the available PowerShell scripts with information about how to call them. Each script can be subtly different but they all require some common elements. For instance every script requires a device_id which gives the script a context to run against. Calling the /get_powershell_scripts API will return an object with two JSON objects inside it: 1) a list of all your devices capable of running a PowerScript and 2) list of all the scripts which are in you script library.

Note that the Request Header includes an authorization Bearer token.

Here is an example of all of your devices. Note that if you are only using VitalSigns with Office365 you might only get back a single device-- the definition of your tenant.

Next in the response is a list of all the scripts. Here is an example of a script (AddTeamMember) with its attributes expanded:

The get_powershell_scripts API lists all the available PowerShell scripts with information about how to call them. Each script can be subtly different but they all require some common elements. For instance every script requires a device_id which gives the script a context to run against. Calling the /get_powershell_scripts API will return an object with two JSON objects inside it: 1) a list of all your devices capable of running a PowerScript and 2) list of all the scripts which are in you script library.

How to Call a Specific Script with /services/execute_powershell_script

To call a specific script, you need to know how to identify it and what parameter it takes. You can find this out by expanding the script items returned by get_powershell_scripts as show below. Here we show the AddTeamMember script:

When you call this API you need to pass the device_id along with any other required parameters. There are two places you can get this value, and both are highlighted in the script below (it is in the URL when looking at the device in the configurator and it is also in the device list array which can be seen using developer tools built into the browser. In the case of Office365 the device_id value will not change over time unless you delete the server and recreate it later.

When calling the API you need to pass the OAuth token in the header, and you need to pass the parameter needed to run the PowerScript.

Here's an example of /services/execute_powershell_script with the token in the Request Header and parameters in the Request Payload: