Intro

As mentioned in Voicegain API Doc most of Voicegain Web API methods use JWT Authentication.

You can learn more about the JWT authentication scheme on the official JWT.io page.

In Voicegain use case, the JWT token carries 3 pieces of information:

• Two are referenced by the the id of the web configuration. In the back-end (server side) web config Id points to:
  • The accountId - this is the ID of your account. Because the accountId is already referenced in JWT, none of the Web API methods require it to be specified in the request body nor query parameters.
  • The contextId - The concept of context is explained in this article. Each JWT token has reference to contextId, so again none of the Web API methods require it to be specified in the request body nor query parameters.
• The Signature of the request. This is hash of the JWT payload and the secret that is not being communicated in the request.

In the future we may add additional time-constrained information to the JWT token, but currently, the JWT token value is fixed given a specific accountId and contextId. 

The JWT token does not expire. Old JWT token can be cancelled by generating a new one.

Generating JWT

You can generate a valid JWT for a context in your account from the Voicegain Web Console by going to Settings -> API Security (this setting is visible in all App Modes except for Transcribe, if you are in Transcribe mode you will have to switch e.g. to STT API). Then press the Regenerate button and a new JWT token will be generated, see image below:

Note, as a security feature, you cannot retrieve/copy previous JWT token (the copy button is grayed out). You will need to generate a new JWT token.

You will have to save locally the newly generated token because it cannot be retrieved again once you leave the web page.

JWT can be regenerated multiple times, but only the most recent JWT will be accepted by the Web API.

Generating JWT on Edge Console

If you are working with Edge instances you will need to generate JWT tokens via the Edge Console that belongs to your Edge Cluster.

Here is how you can get to to the Edge Web Console.

1. In Cloud Web Console switch to Edge mode (the 4 orange squares menu)
2. Select Edge Deployments from the left-side menu. You will see a list of all your Edge deployments/clusters.
3. Load the desired Edge cluster (use Load button)
4. A new browser tab will open with the details of the selected Edge Cluster. At the top there will be name, version, configuration, status and a browser URL of the cluster
5. Click on that URL - this will open the Edge Console (you may need to login).
6. From there it is the same process as generating a JWT from the Cloud Console:
   1. Choose mode that allows for modifying API Security settings, e.g., STT API
   2. Select desired Context (4 gray squares icon). You can also create a new Context.
   3. From left-side menu select Settings->API Security
   4. Click Regenerate and copy the generated JWT

Using JWT

When making Web APi request the JWT has to be included in the "Authorization: Bearer" header. For example, when using curl to make a request:

curl -i -X POST \
-H "Content-Type: application/json" \
-H 'Accept: application/json' \
-H "Authorization: Bearer eyJh…….BOGCO70w" \
-d @data1.json \
https://api.voicegain.ai/v1/asr/transcribe/async

 Short-Lived JWT

The JWT generated from the Web Console should protected on server side and not be used in client web code, otherwise, someone could get easy access to it and run up API requests on your account and you would have to pay for someone else's usage, or, potentially worse, some of your private data (like transcript content) could be exposed.

If in your web client code needs to make direct requests to Voicegain API we suggest using short-lived JWT tokens which can be generated on your server side using /security/jwt API: https://console.voicegain.ai/api-documentation#operation/securityJwtGet

There are two parameters that this method takes:

• aud: Domain from which the requests using this JWT should be allowed.
  Will be inspected only if the request has "Origin" header, which will generally be true for requests coming from web browser.
  Subdomains with wildcards are allowed, see example. Wildcard alone, i.e. "*" is allowed, but not recommended.
• expInSec: Number of seconds from now when the JWT is to expire

The generated short-lived JWT can be used multiple times, but will be valid only within the specified time.