Rate this page:


Most Voximplant Management API calls require authentication and authorization that connect API calls to your account. As there are multiple ways to authenticate and authorize, Service accounts and API keys are the main ones. Learn how to use them with our Management API.


Copy URL

Service accounts

Copy URL

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 has access to the basic Management API methods only.

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.

Please note

Since Voximplant does not store the keys, save it securely on your side.

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)

Token creation

You can create tokens manually.

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

Token in the request

Token in the request

JSON web token

Copy URL

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.


First, go to the Service accounts section to create a new account and generate a JSON with its credentials (AddGenerate 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


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
    header=$header_template || return

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}"


You may need to do run chmod +x token.sh to execute the script properly.

Quick copy-paste

You can create a token.sh by downloading the script from our site.

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


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