Auth parameters

How authentication works

Most of Voximplant HTTP API calls require authentication and authorization that connects API calls to your account. In order to authenticate, identify your account by passing one of the following arguments to an HTTP API call:

   
account_id The account ID, see the API Access section of the Control panel.
account_name The account name.
account_email The account email.

In order to provide security, authorization info should also be provided by passing one of the following arguments to an HTTP API call:

   
api_key The account API key, see the API Access section of the Control panel. Authorization with this parameter is considered deprecated, it is recommended to use service accounts instead.
account_password The account password.

Example

Start a scenario using account_id and api_key:

https://api.voximplant.com/platform_api/StartScenarios/?account_id=1&api_key=eec36d6c-a0eb-46b5-a006-1c2b65343bac&rule_id=1&script_custom_data=mystr

Service accounts

A service account is a way to grant access to the Voximplant HTTP API on behalf of your developer account. If a service account has at least one private key assigned, it can be used for both authorization and authentication purposes. Use the Createkey method to create a new service account and generate a secret key for it. You'll receive a response with the result field in it. Save the result value in a file. Since we don't store the private keys, save them securely on your side.

Next, form a JWT token using RS256. You should substitute this token in every HTTP request to the Voximplant HTTP API. For a better experience, it is recommended to use our API Client Libraries. There are examples of manual creating JWT tokens below.

You can also manage service accounts in the Control panel.

Example (Node.js API Client Library)

  1. Create a service account with the UserManager role, then save the result value as a credentials.json file:

    https://api.voximplant.com/platform_api/CreateKey/?account_id=1&api_key=4ed6065e-1600-442b-60aa-3f8f8481287c&role_id=8
  2. Request the first 20 users of the specified Voximplant application using a service account:

    const VoximplantApiClient = require("@voximplant/apiclient-nodejs").default;
    const client = new VoximplantApiClient();
    client.onReady = function(){
    client.Users.getUsers({applicationId: '1'})
      .then(ev=>console.log(ev))
      .catch(err=>console.error(err));
    };

Example (Bash)

  1. Create the credentials.json file like in the previous example.
  2. 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.

    #!/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
  3. Request the first 20 users of the specified Voximplant application using a service account:
    curl -H "`bash token.sh`" https://api.voximplant.com/platform_api/GetUsers/?application_id=4152784

Subusers

Additionally, a special kind of user account called "subuser" can be created for authentication - see the subusers section of the Control panel. This account type extends the main Voximplant user account with security permissions and HTTP API login capabilities. Using subusers credentials instead of account credentials allows to fine-tune application security. Subuser name and ID are not always unique across accounts and servers. If subuser login is used, the corresponding account must be specified by additionally providing either account_id, account_name or account_email, e.g.:

curl https://api.voximplant.com/platform_api/GetApplications?account_id=1&subuser_login=login&subuser_password=zD2sEdQg
   
subuser_login Verbose name of a subuser.
subuser_password Subuser password.
service account If a subuser has at least one service account, it can be used for both authorization and authentication instead of subuser_login and subuser_password.