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.

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.