Skip to main content
Matrix42 Self-Service Help Center

API Integration

This area provides an overview on integrating with the Silverback server API. The API integration guide aims to provide the administrator with the ability to generate tokens and connect to the API for performing desired management functions.

 

Part 1: Create Token

At a high level, tokens are assigned to existing system users. Tokens can only be assigned to system users with Administrator role.

Token Permission Scope 

There are three scopes that can be assigned to each token:

  • Global Read: This allows actions, which involved retrieving information from the server in a “read-only“ function. If you want to view information about a device or user, but not change anything, this Scope is required.
  • Global Write: This allows actions that change data in the system. If an item in the system will be modified by an API action, this is the Scope that is needed.
  • Global Actions: This allows actions that will perform a “job“ in the system. For example, blocking a device. 

Create Token

To create a token, you must have an existing system user with an Administrator role. When you have a system user you want to allow API for,  perform the following steps:

  • Log in to the Silverback console
  • Navigate to Admin
  • Navigate to User Management
  • Click the Edit option for the user you want to add the API token for, keeping in mind the user must belong to the “Administrator” role to use the API.
  • Scroll down to the Create API Token section.
  • Select the Scope Permissions you require, enter a description.

The description has no technical affect on the token, and is used to help you keep track of your tokens.

  • Click Create and wait until the process has finished. It can be last up to a minute.
  • Click Save
  • Go back to your User and check your new token. 

Part 2: Perform API Calls

The API is accessed via web services, not via a traditional user interface. By using a series of HTTP Requests, such as GET and POST,  Silverback can interact with 3rd Party tools.

Check Documentation

First check all possible APIs under  https://silverback.company.com/api/help .

Ensure to use your Silverback URL instead of the example.

Install Tool Edit section

In general, third part application are written specifically for this. For the purposes of this guide and the demonstration, we will use Postman.

After installation, launch Postman.

Create Collection

  • Click on New and create a New Collection
  • Enter a Name and a Description
  • Go to the Authorization Tab and select as Type : Bearer Token and enter the created token on the right side
  • Click Create

Create a Request Edit section

  • Click on New

  • Click Request
  • Enter a Name (e.g. get devices)
  • Enter a Description (optional)
  • Select your created collection
  • Click Save to your collection 

Configure Request  Edit section

  • Enter your Request URL (e.g. https.silverback.company.com/api/v1/devices)
  • Select the Request Type: GET, PUT, DELETE, POST
  • Navigate to Authorization
  • Check if type is set to Inherit auth from parent 

Authentication Information is stored in collection

Perform Request 

  • Navigate back to Params
  • Click Send 
  • Now you will see a list of your devices 

sb_api01.png

Page Identifier

 if your API call receives more then 50 items, please use the paging Identifier functionality

  • We have for devices and for all other calls a per page item count of 50
  • We have only for users a per page item count of 250 
  • At the end of the Page a paging Identifier is displayed and and total item count
    • pagingIdentifier": "7e269b12-7e7b-470b-8da8-1209890e3452",
    • itemCount: 133 
  • In this case we have 2 additional pages (50 + 50 + 33 = 133) 
  • Copy the identifier value (bold) into the Clipboard 
  • Now you have 2 possibilities:
  • By clicking send a new page will be displayed
  • Click again send to scroll through the pages until the end of the request
  • Was this article helpful?