Theme

Getting started with the REST API ​

There is no better way to automate the management and configuration of Syncplify Server! than scripting against its REST API.

INFO

This article assumes basic familiarity with scripting (bash, zsh, PowerShell, or a language such as Python). No advanced expertise is required, just the ability to make an API call and handle its response.

Every endpoint is described in an OpenAPI 3 definition, which is:

A key security consideration. As enterprise security software, Syncplify Server! deliberately avoids long lived API keys. The authentication flow is:

  1. a login call, which returns a time limited JWT;
  2. that token, as a bearer, on every subsequent call;
  3. automatic expiration of the token, and an explicit logout when you are done.

All paths below are relative to https://<host>:6443/api/v1; the examples assume a local installation at 127.0.0.1:6443. The Basic credential is the base64 of username:password.

The SuperAdmin API, in bash ​

Requires curl and jq. The script logs in as SuperAdmin, lists the virtual sites, patches two settings of the global configuration, and logs out:

bash
#!/bin/bash

# Log in and extract the token from the JSON response
token=$(curl -s --request GET --url https://127.0.0.1:6443/api/v1/sa/login \
  --header 'Authorization: Basic XXXXXXXX' | jq -r '.token')

# Example: list all virtual sites
curl --request GET \
  --url https://127.0.0.1:6443/api/v1/sa/vsites \
  --header "Authorization: Bearer $token"

# Example: modify some aspects of the global configuration
curl --request PATCH \
  --url https://127.0.0.1:6443/api/v1/sa/globalconfig \
  --header "Authorization: Bearer $token" \
  --header 'Content-Type: application/json' \
  --data '{
  "jwtLifeSpan": 30,
  "metricsAllowList": [
    "192.168.10.0/32"
  ]
}'

# At the end of your session, do not forget to log out
curl --request GET \
  --url https://127.0.0.1:6443/api/v1/sa/logout \
  --header "Authorization: Bearer $token"

The script:

  1. logs in as SuperAdmin and receives a short lived JWT that authorizes SuperAdmin calls only;
  2. calls a GET to receive the list and details of every virtual site;
  3. calls a PATCH to modify two settings of the global configuration;
  4. calls the logout API, which invalidates the JWT: from then on every call made with it, even a valid one, is rejected as unauthorized.

If the server uses a self signed certificate, add --cacert with the certificate file to every curl call, or -k to skip verification once you have verified the fingerprint by other means.

The same, in PowerShell ​

powershell
# Log in and get the token
$loginResponse = Invoke-RestMethod -Uri "https://127.0.0.1:6443/api/v1/sa/login" `
    -Method Get `
    -Headers @{ Authorization = 'Basic XXXXXXXX' }

$token = $loginResponse.token

# List all virtual sites
$vSites = Invoke-RestMethod -Uri "https://127.0.0.1:6443/api/v1/sa/vsites" `
    -Method Get `
    -Headers @{ Authorization = "Bearer $token" }

$vSites | Format-Table

# Modify the global configuration
$body = @{
    jwtLifeSpan = 30
    metricsAllowList = @('192.168.10.0/32')
} | ConvertTo-Json

Invoke-RestMethod -Uri "https://127.0.0.1:6443/api/v1/sa/globalconfig" `
    -Method Patch `
    -Headers @{
        Authorization = "Bearer $token"
        'Content-Type' = 'application/json'
    } `
    -Body $body

# Log out to end the session
Invoke-RestMethod -Uri "https://127.0.0.1:6443/api/v1/sa/logout" `
    -Method Get `
    -Headers @{ Authorization = "Bearer $token" }

With a self signed certificate, add -SkipCertificateCheck to every Invoke-RestMethod call (PowerShell 7 and later). $ProgressPreference = 'SilentlyContinue' at the top suppresses the progress noise.

The Admin API of a virtual site ​

WARNING

Everything above uses the SuperAdmin API, exclusively for SuperAdmin tasks. To perform Admin tasks on a virtual site the logic is the same, but you log in through the Admin login API, which takes the ID of the virtual site in its path, and you obtain an Admin JWT instead.

In bash:

bash
#!/bin/bash

# Log in to the Admin API of one virtual site and extract the token
token=$(curl -s --request GET --url https://127.0.0.1:6443/api/v1/adm/login/<virtual-site-id> \
  --header 'Authorization: Basic XXXXXXXX' | jq -r '.token')

And in PowerShell:

powershell
# Admin login API, and acquisition of the Admin JWT from the response
$loginResponse = Invoke-RestMethod -Uri "https://127.0.0.1:6443/api/v1/adm/login/<virtual-site-id>" `
    -Method Get `
    -Headers @{ Authorization = 'Basic XXXXXXXX' }

$token = $loginResponse.token

An account protected by two factor authentication passes its current code in the X-OTP header of the login call; the API definition lists the other headers of the login flow (trusted devices and recovery codes).