***
title: Authorization
subtitle: Learn how to authenticate with Service accounts and API keys to use Voximplant Management API.
---------------------
For a complete documentation index, fetch https://docs.voximplant.ai/llms.txt
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.
## Service accounts
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](https://manage.voximplant.com/settings/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.
Since Voximplant does not store the keys, save them securely on your side.
Next, form [a JWT](https://jwt.io/) 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](https://tools.ietf.org/html/rfc7519#section-4.1.6) (UNIX timestamp)
* **iss** – account\_id
* **exp** – end date, up to **iat**+3600 seconds. It should be [a Numeric date value](https://tools.ietf.org/html/rfc7519#section-4.1.6) (UNIX timestamp)
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.
You can create tokens [manually](/platform/management-api/authorization#json-web-token).
From now on, you should substitute this token in every HTTP request to the Voximplant HTTP Management API, e.g.:
```curl title="Token in the request — Request"
curl -H "Authorization: Bearer ${TOKEN}" https://api.voximplant.com/platform_api/StartScenarios/?rule_id=1
```
```json title="Token in the request — Response"
{
"result": 1,
"media_session_access_url": "http://1.2.3.4:12092/request/eb769701de54cfa5.1539237068.6369268_1.2.3.4/1df792ad965d7105",
"media_session_access_secure_url": "https://1.2.3.4:12092/request/eb769701de54cfa5.1539237068.6369268_1.2.3.4/1df792ad965d7105"
}
```
## JSON web token
To use most of the [Voximplant Management API](https://voximplant.com/docs/references/httpapi) 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](https://manage.voximplant.com/settings/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](/platform/management-api/authorization).
You can do the same via the [CreateKey](https://voximplant.com/docs/references/httpapi/rolesystem#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](https://stedolan.github.io/jq/) tool that is not a built-in command, so you have to install it manually ([download jq here](https://stedolan.github.io/jq/download/)).
```bash
#!/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
```
You may need to do run `chmod +x token.sh` to execute the script properly.
You can create a **token.sh** by [downloading](/assets/images/2020/08/06/jwt.sh) the script from our site.
```bash
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:
```curl title="GetUsers — Request"
curl -H "`bash token.sh`" https://api.voximplant.com/platform_api/GetUsers/?application_id=4152784
```
```json title="GetUsers — Response"
{
"result": [
{
"user_active": true,
"balance": 1,
"user_id": 1,
"user_name": "iden-1",
"user_display_name": "iden-1",
"frozen": false,
"modified": "2020-10-09 08:20:14"
},
{
"user_active": true,
"balance": 0,
"user_id": 2,
"user_name": "iden-2",
"user_display_name": "iden-2",
"frozen": false,
"modified": "2017-01-05 10:12:03"
}
],
"count": 2,
"total_count": 2
}
```