OpenAI ChatKit Sessions API: current setup and migration choices

What OpenAI ChatKit and Sessions do

The current ChatKit guide describes a customizable chat embed with widgets, prompts, tool-invocation support, and file attachments. It has two paths:

• Custom server integration: run ChatKit on your infrastructure and connect it to an agentic service you own.
• Existing Agent Builder-hosted integration: keep an existing Agent Builder workflow connected to ChatKit during OpenAI's transition window.

The “Sessions API” in this article refers to the second path. The browser calls your application, your application authenticates the user, and your server calls POST /v1/chatkit/sessions with its OpenAI API key, workflow ID, and a unique user identifier. The response contains a client_secret for the ChatKit client to open or refresh its session.

Keep the main API key on the server. OpenAI's documented example returns the client secret to the ChatKit client immediately and does not store it. The user field must be a unique identifier for an authenticated application user; a browser-provided identifier without server-side authentication is not the security boundary the documented flow requires.

What has changed for new ChatKit work

The previous “use a hosted workflow” starting point is now time-limited. OpenAI says Agent Builder is being deprecated and is scheduled to shut down on November 30, 2026. Existing users can use ChatKit with a hosted workflow during the transition, but OpenAI directs new applications and migrations to an advanced integration with a server-side agent implementation.

That changes the question a new team should ask. It is no longer only “how do I create a ChatKit session?” It is also “what agent service will the server run, and who will operate it?” A custom integration can use the agentic service the team chooses, but the team owns the decisions around authentication, access control, data handling, tools, deployment, monitoring, and evaluation.

Build a secure ChatKit session flow

For an existing hosted workflow, the session flow has a clear division of responsibility:

1. The application user authenticates with your server.
2. Your server maps that account to a stable, unique user ID.
3. Your server creates the ChatKit session with the workflow ID and that user ID.
4. Your server returns the client secret to the ChatKit client, which opens or refreshes the session.
5. Your application logs and tests failures without exposing the OpenAI API key to the browser.

The client secret is not a substitute for application authorization. Before exposing a tool through the agent behind the chat, decide what information the authenticated user may see, which actions require a separate approval, and how the application will verify the action in the system that performed it.

For example, a returning customer may ask for a refund in a ChatKit conversation. The authenticated session identifies the person using the chat. It does not itself establish that the refund is allowed, execute the refund, or prove that the order system completed it. The agent and application still need to check the relevant policy and order state, request approval where required, and confirm the system result before reporting success.

Test more than the chat widget

Test a session flow with normal and failure cases, not just a successful browser demo:

• An authenticated user receives a session for the intended workflow.
• A missing or invalid application credential is rejected by your server.
• A user cannot access another user's data through a changed browser identifier.
• A tool request is denied or held when policy requires a human decision.
• The final message reflects the real result from the order, helpdesk, or other connected service.

OpenAI's conversation-state guide is also relevant when the agent service behind a custom integration needs history across turns. Its Responses API can use manual history, chained responses, or Conversations objects. Earlier input in a chained conversation remains billed, so test the cost and context behavior of the exact design rather than assuming session persistence is free.

Operate an eesel support teammate through the CLI

ChatKit and eesel solve different parts of the job. ChatKit gives a developer a chat interface and, in the hosted path, a client-secret session flow. eesel CLI operates the existing eesel teammate that works from its connected knowledge and configured instructions. The CLI and dashboard always point to the same teammate and workspace.

This is useful for a support team deciding whether it needs to build a session endpoint at all. A human can use the terminal, a script can consume JSON results, and Claude Code, Codex, or Cursor can inspect the selected teammate before proposing a configuration change. They are operating the teammate, not creating a ChatKit session or calling OpenAI on your behalf.

With Node.js 18.17 or newer, confirm the workspace and teammate before any configuration work:

npx @eesel/cli login
npx @eesel/cli whoami
npx @eesel/cli agents

Then scope the read-only inspection to the support teammate. This prevents a script or coding agent from relying on a saved default in the wrong workspace:

TARGET_EESEL_AGENT="paste-agent-id-or-name-here"
npx @eesel/cli status --agent "$TARGET_EESEL_AGENT"
npx @eesel/cli integrations --agent "$TARGET_EESEL_AGENT"
npx @eesel/cli instructions --agent "$TARGET_EESEL_AGENT"

Ask the coding agent for a read-only report: which sources are connected, whether their content has downloaded, and which instructions govern returning customers, refunds, and human handoff. Do not let it connect accounts, change permissions, or enable automation as a side effect of that report.

After a human approves a change, use --dry-run on the relevant write command before sending it. Before the chat test, review the selected teammate's configured actions and permissions. Disable or contain actions outside the test scope; a held-action queue is not a substitute for knowing what can run without a hold.

Then start a fresh named chat to test a fictional return-customer case:

npx @eesel/cli new --name "returning-customer refund" --agent "$TARGET_EESEL_AGENT"
npx @eesel/cli chat "A returning customer asks for a refund after the normal window. Draft a reply using the approved policy, identify missing evidence, and state when a human decision is required." --agent "$TARGET_EESEL_AGENT"

Review the response for the policy boundary, missing evidence, and honest handoff. This is a CLI support test, not a ChatKit session test. It does not create an OpenAI client secret, authenticate a website user, or prove that a refund happened. If the teammate creates held actions, inspect them with npx @eesel/cli approvals --agent "$TARGET_EESEL_AGENT" and confirm the resulting action in the connected system before saying it succeeded.

The CLI's dashboard-management commands are free; chat is billed work. The JSON output makes a coding agent's assessment inspectable, but it does not replace human approval, representative testing, or result checks.

Choose the path that matches the job

Use ChatKit when you need to build and operate a custom chat interface. For an existing hosted workflow, plan the Agent Builder migration now. For new work, choose a server-side agent implementation and account for the security and operational work around it.

Use eesel when the immediate job is operating a ready-to-work support teammate. Its CLI lets technical users and coding agents work on the same teammate and workspace as the dashboard, while support leads can remain in the tools they already use. Test the approved policy and handoff behavior before expanding a workflow to customers.

Try eesel for support workflows

Try eesel if you want to inspect and operate a support teammate rather than build a custom ChatKit session flow for customer support. Start with an approved policy and small test set, then review the teammate's sources, instructions, replies, and real action outcomes before expanding it.

The Activity view gives a support lead a dashboard-side record to compare with the CLI's JSON output after each controlled test.