Connect OneTwoAgent to your app

1. 1Connect your project with the OneTwoAgent CLI.
2. 2Ask your coding agent to integrate OneTwoAgent.
3. 3Sign in to your application and test the Widget with a real user.

In OneTwoAgent, open Channels>Widget>Install & Connect.

• Make sure you are inside the OneTwoAgent business you want to connect to your application.
• The connection belongs to the currently selected business and its Widget.

Open a terminal in the root directory of the application you want to integrate, then run the setup command below. The CLI opens OneTwoAgent in your browser and starts a temporary secure connection with the terminal on your computer.

npx -y @onetwoagent/cli@latest init --browser

After the CLI starts, your browser opens a OneTwoAgent connection page titled Connect OneTwoAgent CLI. Click Connect CLI. If this business already has a Widget Identity Secret, you may instead see Rotate secret & connect.

Open your coding agent in the same project and send exactly:

• The OneTwoAgent skill installed by the CLI tells the coding agent how to inspect your application and adapt the integration to the framework and authentication system that already exist.

Integrate OneTwoAgent

The identity flow is intentionally split between your server and the browser.

Your application
      |
      | signed-in user
      | stable ID + email
      v
Your server
      |
      | ONETWOAGENT_WIDGET_IDENTITY_SECRET
      v
OneTwoAgent API
      |
      | short-lived identity token
      v
Browser
      |
      v
window.OneTwoAgent.identify(token)
      |
      v
Customer's OneTwoAgent conversation

The Widget can work with both anonymous website visitors and authenticated application users.

User A logs in
-> conversation A

User A logs out

User B logs in
-> fresh conversation B

User B logs out

User A logs in again
-> conversation A returns

The OneTwoAgent signed-in customer integration is framework-agnostic. Your application needs two capabilities: your server can determine which user is currently authenticated, and that user has a stable internal identifier and an email address.

A purely static frontend cannot safely hold the long-lived Widget Identity Secret. The secret must remain server-side.

• A static website can still use the normal anonymous OneTwoAgent Widget.
• To recognize signed-in customers, your application needs a server-side or trusted backend function capable of authenticating the current user, reading their stable ID and email, and calling the OneTwoAgent identity-token API securely.

The CLI writes two different kinds of project configuration. They have very different security properties.

This file contains no long-lived secret. It tells the coding agent and integration which OneTwoAgent business, Widget and API endpoint this project belongs to.

{
  "version": 1,
  "businessId": "your-business-id",
  "publicId": "your-widget-public-id",
  "apiBaseUrl": "https://api.onetwoagent.com"
}

The CLI also stores the value below. This value is secret. It must remain on the server. Treat it like another production API credential.

ONETWOAGENT_WIDGET_IDENTITY_SECRET=...

The CLI + coding-agent flow is recommended. The manual architecture is the same regardless of framework.

• Use the manual integration when your development environment cannot run a coding agent.
• Use it when your team prefers to implement the integration directly.
• Use it when you need full manual control over the integration.

Add the OneTwoAgent Widget once in your global application shell or shared layout.

<script
  src="https://onetwoagent.com/widget/v1.js"
  data-id="YOUR_WIDGET_PUBLIC_ID"
  defer>
</script>

Your application needs a server-only endpoint that reads the currently authenticated user using your existing auth system, returns 401 when no user is authenticated, extracts a stable user ID and email, and exchanges them with OneTwoAgent for a short-lived identity token.

const user = await getCurrentAuthenticatedUser()

if (!user) {
  return response(401)
}

const upstream = await fetch(
  'https://api.onetwoagent.com/api/widget/identity/token',
  {
    method: 'POST',
    headers: {
      Authorization:
        `Bearer ${process.env.ONETWOAGENT_WIDGET_IDENTITY_SECRET}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      externalUserId: String(user.id),
      email: user.email,
      name: user.name,
    }),
  }
)

return upstream.json()

externalUserId must be your application's stable internal customer/user identifier.

Email is required for signed-in customer identity. Read it from the authenticated server-side session or user record.

Name is optional. If your authenticated user already has a name, you may send it to OneTwoAgent.

After your own application confirms that the browser belongs to an authenticated user, request a short-lived identity token from your server endpoint.

const response = await fetch('/api/onetwoagent/identity', {
  credentials: 'include',
})

if (!response.ok) return

const { token } = await response.json()

await window.OneTwoAgent.identify(token)

When your application logs the customer out, reset the Widget identity.

• Call reset() synchronously as part of the logout lifecycle.
• This ensures that the next visitor cannot inherit the previous signed-in customer's Widget identity.
• The application's own logout should continue normally.

window.OneTwoAgent.reset()

Identity tokens are short-lived. The Widget emits otw:identity:required when it needs a fresh identity token.

window.addEventListener('otw:identity:required', async () => {
  if (!currentUserIsAuthenticated()) return

  const response = await fetch('/api/onetwoagent/identity', {
    credentials: 'include',
  })

  if (!response.ok) return

  const { token } = await response.json()

  await window.OneTwoAgent.identify(token)
})

Some applications can switch from one user or account to another without fully reloading the page. After the new application session becomes active, identify the new account.

await window.OneTwoAgent.identify(tokenForNewUser)

An asynchronous identity request may still be running when a customer logs out. Your integration should make sure an old identity request cannot complete after logout and identify the previous customer again.

identify User A starts
-> User A logs out
-> Widget identity is invalidated/reset
-> old User A request finishes
-> old result must be ignored

For most applications, install the Widget globally and control visibility from OneTwoAgent. This keeps page-placement decisions in Widget Settings instead of scattering Widget conditions throughout your application code.

• Open Channels>Widget>Advanced -> Where the Widget appears.
• The underlying settings are Allowed Pages and Excluded Pages.

Turn Page Restrictions off.

Page Restrictions: Off

Leave Allowed Pages empty. Add the paths below to Excluded Pages.

/login
/register
/checkout
/checkout/*

Add the paths below to Allowed Pages and leave Excluded Pages empty.

/dashboard
/dashboard/*

Allowed Pages define where the Widget may appear.

/dashboard
/dashboard/*
/products/*

Excluded Pages define where the Widget must never appear.

/login
/register
/checkout
/admin/*

* can match multiple characters.

Allowed Domains and Page Restrictions solve different problems.

Signed-in identity connects Widget conversations to the authenticated customer.

User A logs in
-> OneTwoAgent identifies User A
-> User A conversation appears

User A refreshes
-> User A conversation remains

User A logs out
-> Widget identity resets

User B logs in
-> User B gets their own conversation

User B logs out

User A logs in again
-> User A's previous conversation returns

The most important security boundary is simple.

Widget Settings allows you to rotate the identity secret.

• Rotate when you suspect the secret was exposed.
• Rotate when you intentionally reconnect the integration.
• Rotate when you want the previous credential to stop working.

Before considering signed-in identity complete, test with at least two real application accounts.

Troubleshooting by symptom.

Before going live:

• Widget script installed once
• Correct OneTwoAgent business connected
• Allowed Domains configured if needed
• Page visibility configured
• ONETWOAGENT_WIDGET_IDENTITY_SECRET is server-only
• Stable application user ID is used
• Email comes from authenticated server session
• identify(token) runs after authentication
• reset() runs on logout
• Identity refresh event is handled
• User A survives refresh
• User B cannot see User A
• User A history returns when User A signs in again