Securing the embedded chat

Securing an embedded chat includes how identity is established, how access is controlled, how context is trusted, and who owns operational safeguards.
Security enforcement depends on configuration choices, which include whether authentication is enabled.
When enabled, all communication between your web application and IBM watsonx Orchestrate relies on authenticated requests, signed tokens, and encrypted payloads through public-key cryptography and JSON Web Token (JWT) authentication.

Security modes

Enable security to authenticate client requests and to make sure that only authorized applications can start the embedded chat APIs. Disable it for anonymous access to the embedded chat in specific use cases.

You can enable or disable security depending on the needs of your application:

Enable security to authenticate client requests and ensure that only authorized applications can access the embedded chat APIs.
Disable security to allow anonymous access when identity is not required.

Security enabled

Security for embedded chat is enabled by default at instance level, but it is not active until you explicitly configure the required cryptographic assets and register them with your instance. The embedded chat does not work until the steps in the Configuring security for embedded chat section are successfully completed.

When security is enabled, you must make sure that:

Every requests to the embedded chat APIs include a valid JWT.
The JWT must be signed by using your client private key.

The watsonx Orchestrate service validates the token by using the client public key to help ensuring request authenticity and integrity. This action prevents unauthorized access to your instance.

Security disabled

Disable security to allow anonymous users to access the embedded chat in the web application. Use this mode only when anonymous access is explicitly required, such as public demonstrations, anonymous chat use cases, and low risk environments with no access to sensitive systems or data.

Before you disable security, you must carefully review all integrations in your instance to avoid unintended data exposure, and make sure that your instance:

It does not show or provide access to sensitive data.
It does not have tools that are configured with functional credentials that access sensitive data in protected systems.

When security is disabled, anonymous authentication is enabled for a limited set of APIs that are required to get your chat to work for anonymous users.

Security model for embedded chat

The embedded chat security model use asymmetric RSA key pairs and JWT authentication. It uses RSA public‑key cryptography to establish trust, authenticate requests, and protect sensitive payload data that is exchanged between your web application and the watsonx Orchestrate instance.

When security is enabled, both authentication and confidentiality are enforced through JWT signing and encrypted payloads. The security model uses two independent RSA key pairs, each with a clearly defined role.

Client Application Key Pair

This key pair represents the identity of your web application.

Generated by: You or your organization’s key management infrastructure
Public key:
- The public key is uploaded to watsonx Orchestrate during configuration.
- It is used to verify JWT signatures.
Private key:
- The private key remains under your control and must be protected by using industry‑standard secret management practice.
- It is used to sign JWTs sent to watsonx Orchestrate.

This key pair allows watsonx Orchestrate to:

Authenticate the calling application.
Verify token integrity.
Reject unauthorized or tampered requests.

IBM Key Pair

This key pair is generated and managed by the watsonx Orchestrate instance.

Generated by: watsonx Orchestrate
Optional usage:
- This key pair is optional and is only required if your application needs to pass an sso_token for OBO (On-Behalf-Of) flow.
- If you are not using OBO, you don’t need to encrypt or send a user_payload.
Public key:
- The public key is shared with your application.
- Your application uses this key to encrypt the user_payload section of the JWT sent to watsonx Orchestrate.
Private key:
- The private key is stored securely by watsonx Orchestrate.
- It is used to decrypt the user_payload section of the JWT at run time.

This key pair can ensure that:

Sensitive user context is encrypted in transit.
Only watsonx Orchestrate can access the encrypted payload.
Payload contents cannot be inspected or modified by intermediaries.

Note:As of today, user_payload supports only sso_token.

Authentication and access control

Authentication uses JSON Web Tokens (JWTs) to convey user identity and context. When security is enabled, your web application must complete the following tasks:

Generate a JWT signed with the client private key (Client Key Pair). The token signature must correspond to the public key configured in watsonx Orchestrate.
Include the JWT in every request sent to the embedded chat APIs.

For each request, the watsonx Orchestrate service verifies the token signature and validates the token by using a public key that you configure as part of the security configuration.

Key and token lifecycle management

Your web application is responsible for managing the keys and token lifecycle, including:

Generating tokens by using approved signing keys.
Managing token expiration and renewal. To refresh a token during an active chat session, use the updateIdentityToken() method.
Rotating and revoking keys according to your security policies. To rotate keys, disable security and re-enable it with the newly generated keys.

Access control

The JWT determines the authorization context for the embedded chat session and the associated instance. The embedded chat initiates and authorizes all API calls and instance access under User permissions.

Anonymous access

If user identity and signed user context are not required, and no sensitive data is exposed, you can disable security to allow anonymous access. For more information, see the Security disabled section.