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.
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.
First check all possible APIs under https://silverback.company.com/api/help .
Ensure to use your Silverback URL instead of the example.
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.
- 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
- 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
- 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
- Navigate back to Params
- Click Send
- Now you will see a list of your devices
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:
- Change the Request URL to: https://docu.imagoverum.com/api/v1/devices?page=7e269b12-7e7b-470b-8da8-1209890e3452 and click send
- Or add under params the following
- Key = page
- Value = 7e269b12-7e7b-470b-8da8-1209890e3452
- Click send
- By clicking send a new page will be displayed
- Click again send to scroll through the pages until the end of the request