Rate this page:

How to use API keys & Service accounts

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

API Keys (deprecated)

Formally, use of API keys is deprecated since there is a new advanced functionality – Service accounts. However, it still works perfectly especially if you are the only person who has access to a Voximplant account.

Go to the API Keys section of the Control panel where you can obtaion your account_id and api_key. Then just substitute them in a request to the HTTP API, e.g.:

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

The request will be processed with maximum permissions.

Service Accounts

A service account is a way to grant access to the Voximplant HTTP 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 HTTP API methods only. Please see this article for details.

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.

ATTENTION

Since we don't store the keys, save it securely on your side.

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

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

You can create tokens manually (see the Service accounts section), but for a better experience it is recommended to use our API Client Libraries.

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

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