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 and 2025 more authentication functionality will be provided and authentication will eventually be made mandatory.

API Authentication

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 beyond bots, such as dialog history exports and provisioning, will require the use of service accounts 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.

Webhook Authentication

Why

Consumers of webhooks have the challenge of verifying that a request is legitimate and comes from the expected CVG environment. For example, a production bot might not want to accept requests from a staging environment, for example, when configured like that by accident. But more importantly, requests performed by unsolicited parties need to be reliably prevented.

Who

Webhook authentication is relevant for any system that receives webhook requests from CVG, which includes but is not limited to:

  • All bots

  • All consumers of integration webhooks

  • All assist systems

These systems must be able to prove a request is legitimate.

How

CVG provides three mechanisms for webhook authentication:

  1. Asymmetric Cryptographic Signatures (Recommended method)

  2. Bearer Tokens (Method for legacy systems)

  3. IP Address Whitelisting (Discouraged method)

Asymmetric Cryptographic Signatures

All webhook requests performed by CVG are cryptographically signed using an asymmetric signature scheme.

The signature conforms to the JSON Web Signature (JWS) standard (see RFC 7515) and is included in the X-CVG-Signature header of every request. The signature is calculated over the entire raw request body. Please make sure that no parsing or transformation of the request body happens before signature verification.

The header of the JWS contains these important fields:

  • kid: This field specifies the key used to sign the request.

  • alg: This field specifies the signature algorithm used.

  • time: This is the timestamp of the HTTP request in epoch milliseconds in UTC. Each retry attempt will have a different timestamp.

The signature must be verified against the JSON Web Key Set (JWKS) provided by this endpoint. If the key used to sign the request is not found in that JWKS, then the key must be considered revoked. Make sure that the verification is performed against the keys of the correct CVG environment, as each environment maintains its own key set with unaligned rotation rhythms.

To mitigate replay attacks, use the time field of the JWS header to check if the request is not too old. CVG will not usually send events that are older than a few seconds, but also make sure to account for some clock skew between CVG and the receiving systems.

New signing keys will be generated every week, and each key is valid for 2 weeks. Keys can be cached locally and upon observing a new key, the JWKS should be re-fetched to check if the new key is valid. The endpoint can also be probed periodically to check for new keys. The JWKS response will include an ETag, which can be included when refreshing using the If-None-Match header to avoid unnecessary data transfer when the key set has not changed.

Bearer Tokens

Everywhere, where a webhook URL can be configured, a bearer token can optionally also be configured. This token is assumed to be an opaque token compatible with the Bearer authentication scheme (see (RFC 6750 Section 1.2)[https://datatracker.ietf.org/doc/html/rfc6750#section-1.2)).

When a token is configured, CVG will include an Authorization header in every request to the webhook URL with the value Bearer <token>. Consumers of the webhook can then verify that token.

IP Address Whitelisting

This method of authentication is highly discouraged, because CVG’s network infrastructure is not covered by its stability guarantees. At any point in time and without prior notice, it might be necessary for technical reasons to change our infrastructure in a way that results in different IPs being presented to webhook consumers.

If IP whitelisting is still desirable, it is advisable to whitelist the wider network (e.g., as per RIPE’s listing) rather than individual IP addresses.