Authorization

Most Voximplant Management API calls require authentication and authorization, which link API calls to your account. Since there are various methods of authentication and authorization, Service accounts and API keys are the primary ones. For more information on how to use them, refer to our Management API documentation.

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:

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.:

To use most of the 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 our 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: