Security - Cognigy Documentation

Security Aspects of the Cognigy Click To Call SDK

This page covers security aspects of the Cognigy Click To Call SDK, including transport encryption, credential handling, and best practices.

Transport Security

HTTPS Requirement

The SDK requires a secure context (HTTPS or localhost) to function. WebRTC APIs such as RTCPeerConnection and getUserMedia are not available in insecure contexts.

WebSocket Security

The SDK connects to the SIP server using WSS (WebSocket Secure), providing TLS encryption for all SIP signaling traffic. The WebSocket URI is retrieved from the endpoint configuration and must use the wss:// scheme.

Media Encryption

WebRTC media streams (audio) are encrypted using DTLS-SRTP (Datagram Transport Layer Security — Secure Real-time Transport Protocol). DTLS handles the key exchange, and SRTP encrypts the audio data. This is enforced by the browser’s WebRTC implementation and requires no additional configuration.

Configuration Fetch

During connect(), the SDK sends an HTTPS request to the endpointUrl to retrieve SIP credentials, the SIP server address, and session parameters. Because this response contains authentication credentials, the request is always made over TLS-encrypted HTTPS.

Credential Handling

SIP Credentials

SIP credentials are fetched from the Cognigy backend via the endpointUrl during connect(). The credentials are:

Generated by the Cognigy backend and scoped to the session.
Managed internally by the SDK — they are never exposed to your application code.
Used only for SIP registration and call signaling.

User Identification

The optional userId parameter is used for session identification only. It is sent as part of the SIP URI for registration.

Don’t pass sensitive information such as passwords, tokens, or personally identifiable information (PII) as the userId.

Network Security

Firewall Configuration

The SDK requires the following network access:

Protocol	Direction	Purpose
HTTPS	Outbound	Fetch endpoint configuration
WSS	Outbound	SIP signaling via WebSocket
UDP/TCP	Outbound	RTP media streams (audio)

ICE and TURN Servers

If your network uses a restrictive firewall or NAT, configure STUN/TURN servers via the pcConfig option to ensure media connectivity:

const client = await createWebRTCClient({
  endpointUrl: 'https://your-cognigy-environment.com/token',
  pcConfig: {
    iceServers: [
      { urls: 'stun:stun.l.google.com:19302' },
      {
        urls: 'turn:your-turn-server.com:3478',
        username: 'user',
        credential: 'password'
      }
    ]
  }
});

TURN servers relay media traffic when direct peer-to-peer connections are blocked. Use TURN with TLS (turns:) for encrypted relay traffic.

Best Practices

Serve your application over HTTPS in production. WebRTC APIs require a secure context.
Use TURN servers with TLS in restrictive network environments.
Do not log SIP credentials. The SDK handles credentials internally — avoid intercepting or logging them.
Do not pass PII as userId. Use an opaque session identifier instead.