Widget connections and approvals

Let signed-in customers connect their own accounts in your widget. Set up services, scope account access, and manage saved approvals from one guide.

Let each customer use their own connected accounts while your team chooses the services and tools available from Actions. Customers connect and review requests inside the widget; they do not need an OpenCX dashboard account.

Use Widget v5 and authenticate customers through your backend. Anonymous visitors and an unsigned email or externalId cannot authorize a personal connection. See Install Widget and Widget authentication.

Set up personal connections

1. Add the service in Actions

   Add an MCP server and choose Each user — their own account. Enable the server and choose which tools your agent may use. Choose Our team — one shared account when everyone should use a connection your team manages instead.

   Fill in Capabilities with the actions the service supports, such as creating orders or tracking shipments. The agent uses this description to recognize when a request needs a connection, even when the service hides its tools until the customer authorizes access. Keep it current when you change the service or disable tools; do not include credentials or customer data. The description does not grant access: after authorization, the agent checks the tools available to that customer.

   Connection ownership is fixed when you create the server. See MCP servers for supported authentication and tool controls.

2. Authenticate the customer from your backend

   Resolve the customer from your application’s signed-in session, call the widget authentication endpoint, and pass its result as user.token. Keep the organization API key on your server.

   Include mcp_access: {} in the backend authentication request to enable all personal servers in your organization. Omitting mcp_access keeps chat-only authentication. Optionally set mcp_access.server_ids to restrict that customer to a list; an empty list allows none. Include mcp_access.account_id when customers can switch accounts or workspaces.

   Follow the authentication example and token renewal guidance.

3. Opt the embed into connection requests

   Set streaming: true and capabilities: { connections: true }, and ensure your organization supports streaming. Both connection UI and requests are off when the capability is omitted. A token with mcp_access grants the permitted scope; it does not turn on the embed UI.

   const options = {
     token: '<WIDGET_TOKEN>',
     user: { token: '<AUTHENTICATED_CONTACT_TOKEN>' },
     streaming: true,
     capabilities: { connections: true },
   };
   

   This works in the popover and Companion layouts. A headless client must supply the connection UI before declaring support.

4. Let the customer connect when needed

   When a request needs account access, the widget shows Connect. The customer completes the service’s authorization flow, returns to the widget, and the request continues after access is confirmed.

   Saved connections belong to the signed-in customer and account. Starting a new session keeps those connections. Pending prompts stay with their original session until answered, cancelled, or expired; they do not carry into the new session.

Review tool requests

A connected service can request a form or a simple approval. The widget shows that request, sends the customer’s answer back to the waiting tool, and lets it continue.

• Approve once accepts the current simple approval request.
• Always allow remembers approval only for the same connected account, server, tool, inputs, and form. Changed requests still ask.
• Decline rejects the request. Cancel closes it without accepting.
• Other forms require the customer to review and submit their answers each time.

Connecting an account and approving a tool request are separate decisions. A remembered approval does not override the service’s access checks or your configured action permissions. See form requests for supported fields, validation, and expiry.

Manage connections and saved approvals

From the widget session list, open Connections and select a service. Only personal connections for the signed-in customer and account appear here; your team’s shared connections stay in Actions.

Action	Result
Saved approvals → Remove approval	Remove one remembered approval. The next matching request asks again; the account stays connected.
Disconnect	Remove the personal connection and its saved approvals. The customer must connect again to use it.
Connect again successfully	Replace the saved credentials and clear remembered approvals. Starting or cancelling replacement authorization keeps the existing connection.

These settings stay with the customer and account across sessions.

Use a connection from your backend

If your backend also needs the customer’s connected account, enable Reuse connections in your backend on that personal server. This is off by default. Your backend can receive a connection-ready notification and retrieve the current access token with a separately scoped API key.

Follow Reuse a customer connection in your backend for webhook verification, customer/account matching, and token retrieval. Use each token only with the service and permissions it was issued for.

If your backend already owns the downstream credentials, configure your authenticated gateway as the server instead. Your gateway handles its setup flow and verifies access when the widget retries; returning from a setup page alone does not prove the customer is connected.