ВОЙТИ

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.
session_id The API session ID. Tip: this is a temporary value provided by the Logon method.

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.

Example (Node.js)

  1. Create a subuser 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. Create a token.js file in the same folder with the following code:

    const fs = require('fs');
    const jwt = require('jsonwebtoken');
    
    let key;
    const path = process.env.PWD + "/credentials.json";
    
    fs.readFile(path, 'utf8', (err, data) => {
      if (err) throw err;
      this.key = JSON.parse(data);
      console.log(generateToken());
    });
    
    const generateToken = () => {
      const nowTS = (+new Date()) / 1000 | 0;
    
      const tokenData = {
        iss: this.key.account_id,
        iat: nowTS,
        exp: nowTS + 3600
      }  
      const token = jwt.sign(tokenData, this.key.private_key, {
        algorithm: 'RS256',
        header: {
          kid: this.key.key_id
        }
      });  
      return token
    }
  3. Request all users of the specified Voximplant application using a service account:
    curl -H "Authorization: Bearer `node token.js`" https://api.voximplant.com/ platform_api/GetUsers/?application_id=4152784

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:

    #!/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 all 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.
session_id The API session ID. Tip: this is a temporary value provided by the Logon method.
subuser_password Password that can be used instead of session_id.
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 session_id/subuser_password.