Authorization

Most Voximplant Management API calls require authentication and authorization, which link API calls to your account. Service accounts and API keys are the primary authentication methods. For method-level HTTP documentation, see the Management API reference.

Service accounts

A service account is a way to grant access to the Voximplant Management API on behalf of your developer account. You can manage the permissions of each service account by assigning one or more roles to it. If a service account has no assigned roles, it will only have access to the basic Management API methods.

Go to the Service accounts section and click Add in the upper right corner. In the dialogue opened, click Add role and specify as many roles as you need. For example, if you want to enable this new account to just start cloud scenarios, add the Scenarios role. Put a short description (if needed), click Generate key, and specify where to save a private key.

Next, form a JWT using RS256. The required fields are:

• kid – key_id to be specified in the header section
• iat – start date, it should be a Numeric date value (UNIX timestamp)
• iss – account_id
• exp – end date, up to iat+3600 seconds. It should be a Numeric date value (UNIX timestamp)

The parent account can manage all child accounts, so it is not necessary to create service accounts for all child accounts. To manage a child account, specify the child account ID in the iss field of the JWT token.

From now on, you should substitute this token in every HTTP request to the Voximplant HTTP Management API, e.g.:

1
curl -H "Authorization: Bearer ${TOKEN}" https://api.voximplant.com/platform_api/StartScenarios/?rule_id=1

1
{
2
  "result": 1,
3
  "media_session_access_url": "http://1.2.3.4:12092/request/eb769701de54cfa5.1539237068.6369268_1.2.3.4/1df792ad965d7105",
4
  "media_session_access_secure_url": "https://1.2.3.4:12092/request/eb769701de54cfa5.1539237068.6369268_1.2.3.4/1df792ad965d7105"
5
}

JSON web token

To use most Voximplant Management API functions, you need to generate a JSON Web Token. Learn how to do that via CLI and a bash script.

Creating

First, go to the Service accounts section to create a new account and generate a JSON with its credentials (Add → Generate a key). Do not forget about the role; it allows using certain features and making certain requests. Then save the result value as a credentials.json file.

Read more about authentication through service accounts.

You can do the same via the CreateKey method of the Management API.

Next, create a token.sh file in the same folder with the following code. Note that the code uses a jq tool that is not a built-in command, so you have to install it manually (download jq here).

$
#!/usr/bin/env bash
$
$
credentials="${PWD}/credentials.json"
$
$
account_id=$(cat $credentials | jq -r ".account_id")
$
key_id=$(cat $credentials | jq -r ".key_id")
$
rsa_secret=$(cat $credentials | jq -r ".private_key")
$
$
timestamp() {
>
    date +"%s"
>
}
$
$
test_payload=$( jq -n \
>
    --arg iat "$(timestamp)" \
>
    --arg iss "$account_id" \
>
    --arg exp "$(($(timestamp)+3600))" \
>
    '{
>
        iat: $iat | tonumber,
>
        iss: $iss | tonumber,
>
        exp: $exp | tonumber
>
    }'
>
)
$
$
set -o pipefail
$
$
header_template=$( jq -n \
>
    --arg typ "JWT" \
>
    --arg alg "RS256" \
>
    --arg kid "$key_id" \
>
    '{typ: $typ, alg: $alg, kid: $kid}'
>
)
$
$
b64enc() { openssl enc -base64 -A | tr '+/' '-_' | tr -d '='; }
$
json() { jq -c . | LC_CTYPE=C tr -d '\n'; }
$
rs_sign() { openssl dgst -binary -sha"${1}" -sign <(printf '%s\n' "$2"); }
$
$
sign() {
>
    local secret=$rsa_secret
>
    algo=RS256
>
    header=$header_template || return
>
    payload=$test_payload
>
>
    signed_content="$(json <<<"$header" | b64enc).$(json <<<"$payload" | b64enc)"
>
>
    sig=$(printf %s "$signed_content" | rs_sign "${algo#RS}" "$secret" | b64enc)
>
>
    printf 'Authorization: Bearer %s.%s\n' "${signed_content}" "${sig}"
>
}
$
$
sign

$
curl https://voximplant.com/assets/images/2020/08/06/jwt.sh 
$
--output token.sh

Usage

Use your JWT in CLI via curl with the -H key specified. For example, request the first 20 users of the specified Voximplant application:

1
curl -H "`bash token.sh`" https://api.voximplant.com/platform_api/GetUsers/?application_id=4152784

1
{
2
  "result": [
3
    {
4
      "user_active": true,
5
      "balance": 1,
6
      "user_id": 1,
7
      "user_name": "iden-1",
8
      "user_display_name": "iden-1",
9
      "frozen": false,
10
      "modified": "2020-10-09 20:20:14"
11
    },
12
    {
13
      "user_active": true,
14
      "balance": 0,
15
      "user_id": 2,
16
      "user_name": "iden-2",
17
      "user_display_name": "iden-2",
18
      "frozen": false,
19
      "modified": "2017-01-05 10:12:03"
20
    }
21
  ],
22
  "count": 2,
23
  "total_count": 2
24
}