Authentication

As of the end of 2023 all of our API endpoints started accepting optional explicit authentication. Additionally all bots are supplied with temporary access tokens per active dialog. Over the span of 2024 more authentication functionality will be provided and authentication will eventually be made mandatory.

Why

Explicit authentication has several advantages even beyond the direct security improvements:

  • better control over the lifecycle of access tokens

  • improved audit logging capabililties for tracability

  • improved access control capabilities

  • more functionality of CVG can be made available for automation via APIs (e.g. automated project management, automated dialog history exports and more)

Who

Authentication primarily affects two areas in CVG:

  1. Custom bots

  2. Automation (Provisioning, dialog history exports, …)

Bots using any of the ready-made integrations built by us or our partners will use authentication without requiring any change to existing dialog designs.

How

Custom bots are being supplied with a short-lived authentication token in every event (checkout e.g. the /session specification), which can be used during the lifetime of a particular dialog. This token is valid for all API requests that are related to a specific dialog. The exact expiry time depends on the project configuration of the bot, but each token will be valid for at least as long as the dialog runs plus some head room for certain operations that happen after the dialog ended (e.g. downloading recordings). These tokens are opaque strings (they have no meaning to the bot) and should just be passed as a Bearer token into the Authorization header of any requests to CVG that require authentication.

Automation use-cases such as dialog history exports and provisioning will require the use of service accounts (to be released in 2024) to authenticate during API requests. These will consist of a client credentials pair (client_id and client_secret) which can be exchanged for a short lived access token using our authorization server. This process follows the OAuth2 standard.