Skip to main content

API Key

Overview​

To support integrations in CX platforms that do not have OAuth2 (SSO), or have no native integration allowing them to use JWT's, we also support API key authentication.

In this case, a widget is loaded within the platform with an API key included in the URL, together with the user info. When loaded in the browser, the widget then uses the API key and user info in the URL to authenticate the current user.

Security Risk

This form of authentication is not safe, and only intended as last resort. Any agent can easily find the API key within the browser developer console, and reuse it to log in as any other agent, including editors and managers (privilege escalation).

Current Usage​

There are currently two platforms using this form of authentication:

  • LiveEngage
  • Genesys WDE

Authentication Flow​

When the Deepdesk widget is loaded within the CX platform, the following steps are performed:

  1. Backend receives a request for the widget, e.g. https://vattenfall.deepdesk.com/widget/liveengage?apikey=****&agent_id=1&agent_name=Test
  2. Backend redirects to /v2/widget/liveengage with the exact same query parameters (the Backend endpoint is there only for backwards compatibility)
  3. When the widget is loaded, it takes the API key and user info from the URL, and posts to the Admin API authentication endpoint https://vattenfall.deepdesk.com/apis/admin/session/api-key/
  4. The authentication endpoint sets the required session and JWT cookies in the response, logging the user in

Sequence Diagram​

The following sequence diagram illustrates the authentication flow:

Secret Management​

Each account has its own API key, which is a managed secret called <account>_integration_api_key.

Example:

  • Account: vattenfall
  • Secret name: vattenfall_integration_api_key

Security Considerations​

⚠️ Important Security Limitations:

  • Not Recommended: API key authentication should only be used as a last resort when other methods are not available
  • Vulnerability: API keys are exposed in the browser and can be extracted from the developer console
  • Privilege Escalation Risk: Any agent with access to the API key can impersonate any other agent, including those with higher privileges
  • Prefer Alternatives: Always prioritize SSO or JWT authentication when possible