Connect OneTwoAgent to your app

Account-aware support is production. The fastest way to add the Widget, signed-in customers and live account data to your app is the OneTwoAgent CLI plus the coding agent you already use, such as Claude Code, Cursor or Codex.

1. 1Run the OneTwoAgent CLI in your app and click Connect in the browser.
2. 2Tell your coding agent: Integrate OneTwoAgent fully into this app and deploy it. Use the installed OneTwoAgent skill and finish by verifying production.
3. 3Approve the account data your agent proposes: one click in the browser.
4. 4Your agent verifies production with onetwoagent doctor; you sign in once when it asks.

Open a terminal in the folder of the web app your customers sign in to (in a monorepo, that app’s folder) and run the command below. You can also ask your coding agent to run it. It opens OneTwoAgent in your browser for the business currently selected in your dashboard (Channels → Widget → Install & Connect shows the same command).

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 this one sentence. You do not need to explain your auth library, database, plans or hosting: the installed skill tells the agent to inspect the repository and adapt everything to what your app already has.

Integrate OneTwoAgent fully into this app and deploy it. Use the installed OneTwoAgent skill and finish by verifying production.

When the account endpoint is ready, your coding agent runs the configure command. Your browser shows exactly what OneTwoAgent may read: the endpoint, the account sections and each support view with its description. An owner or admin clicks Approve.

• The CLI generates a separate read credential in your server env file. It is never printed and never sent to the browser in a URL.
• Approving again with a changed list replaces the configuration. Nothing is read until a signed-in customer asks a question that needs it.

npx -y @onetwoagent/cli@latest account-lookup configure onetwoagent.account-lookup.json

Your coding agent finishes by running doctor, and you can run it any time. It checks the project connection, the installed skill, the server environment (by name only), the Widget and identity wiring, your OneTwoAgent configuration, the Content-Security-Policy of your production pages, and what OneTwoAgent actually observed in production: the Widget loading, signed-in identity, a signed-in conversation and live account reads.

• Every problem comes with a code and a concrete fix, for example IDENTITY_EXCHANGE_FAILED at accountContext.facts.usage.0.used, ALLOWED_DOMAIN_MISSING or CSP_WIDGET_BLOCKED.
• Checks that need a person in production, such as signing in once and asking one question, are reported as manual checks instead of a false pass.
• --json gives coding agents a stable result. Secrets, account data and conversations are never printed.

npx -y @onetwoagent/cli@latest doctor --url https://app.example.com

Besides the built-in sections, your app can offer up to 8 support views: short, read-only lists named after your own product, so the AI agent can answer questions like “Which of my projects are stuck?” or “Do I have conversations that need a reply?”. Custom support views are available in production.

• You choose the names and descriptions (for example projects, orders, shipments, deployments, campaigns or conversations). OneTwoAgent only owns the transport, the limits and the authority.
• Each answer is at most 6 records with a title, a status, an updated time, a short summary and up to 4 simple fields. No HTML, links, secrets or whole database rows.
• Your server rechecks the customer’s session and permissions on every read. The AI agent can only pick a view you approved; it never chooses the user, workspace or address.
• For conversation-like data, expose the subject, status and a short safe excerpt, never full message bodies or whole mailboxes.

Signed account snapshots and fresh account lookup are available in production. Pick the smallest mode that answers your customers' questions; each mode adds to the one before it.

• Identity only: name/email from your authenticated server; no lookup setup required.
• Identity + signed snapshot: explicitly selected customer-visible facts at observedAt, with a maximum five-minute proof lifetime.
• Snapshot + fresh lookup: one optional read-only endpoint in your existing backend; the agent requests one allowed section or support view only when a fresh check is needed.

Build it with @onetwoagent/integration (npm) on a JavaScript or TypeScript server, or with the native adapter for Python, PHP, Ruby, Go, Java or .NET that ships in the CLI skill. You connect isSessionLive to your existing live session and workspace membership checks, and readSection/readView to explicit customer-visible projections; the adapter handles the read credential, request validation, the support grant, result limits and fixed errors.

• Built-in sections: subscription, access, usage, jobs and integrations, plus up to 8 approved support views. The model controls only which section or view to read; user/workspace/business, grant, URL and credentials come from trusted server context.
• Add optional accountReadGrant { reference, expiresAt } to the existing identity exchange. It is a short scoped reference, not a cookie or session token, and expires no later than the signed snapshot.
• Configure the exact HTTPS endpoint, sections and views with onetwoagent account-lookup configure, approved by an owner or admin in the browser (or the OWNER/ADMIN account-lookup API). A separate encrypted read credential authorizes the endpoint; the Widget identity secret remains hash-only and cannot administer it.
• The endpoint rechecks live session/delegation and membership on every call. Logout/removal causes the next lookup to fail even if the signed snapshot is still valid.
• No unrestricted SQL, write actions, full ORM records, hidden flags, stack traces, DOM access or session replay. Never expose secrets to the model, browser, .onetwoagent.json or logs.

npx -y @onetwoagent/cli@latest account-lookup configure onetwoagent.account-lookup.json

{
  "expectedRevision": 0,
  "enabled": true,
  "schemaVersion": 1,
  "endpoint": "https://your-app.example/api/onetwoagent/account",
  "sections": [
    "usage",
    "jobs"
  ],
  "views": [
    {
      "id": "projects",
      "description": "Current projects with their status"
    }
  ]
}

• A lookup never changes the original snapshot or conversation. Fresh successful fields override that snapshot section for this turn. Other snapshot fields remain observations at their original observedAt.
• Fresh results last at most 30 seconds and never exceed proof/grant expiry. The 3-second total network deadline includes DNS/connect/body; JSON is limited to 8 KiB and 10 objects total, with exact field schemas. HTTPS, pinned global IPs and valid TLS are required; redirects and compressed responses are rejected.
• Timeout, 5xx or invalid data means current state could not be checked; old snapshot facts cannot masquerade as a successful live check. A 401/403 requires reauthentication and prevents private snapshot/history fallback.
• Same-snapshot bounded dialogue remains. A clarification consuming a lookup-derived reply inherits its shorter expiry and grant/config provenance. Old dialogue is context, never authority for current account facts. Changed snapshots still start a new AI history boundary.
• One lookup per customer turn, no automatic HTTP retry or cross-turn result cache. A lost result is uncertain; recovery requires a new customer turn. Existing billing and Pause/Schedule apply; lookup has no separate credit charge.
• AI receives only permitted projected fields, provenance, the question and bounded dialogue. Apply your application's disclosure/consent policy. Reset clears local presentation but does not instantly revoke historical conversation tokens or cancel a request already in flight.

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://widget.onetwoagent.com/widget/v1.js"
  data-id="YOUR_WIDGET_PUBLIC_ID"
  defer>
</script>

Extend your existing policy; never disable it. With a nonce-based policy, give the Widget's script tag your page nonce: every style, stylesheet link and script the Widget injects reuses it, so no 'unsafe-inline' is needed for the Widget.

• script-src: https://widget.onetwoagent.com (plus your nonce on the Widget's script tag when you use nonces)
• style-src: the same nonce, or your existing 'unsafe-inline'
• connect-src: https://api.onetwoagent.com wss://api.onetwoagent.com https://widget.onetwoagent.com
• img-src: https://widget.onetwoagent.com https://*.supabase.co data: blob:
• Only with a Google font in the Widget's appearance: style-src https://fonts.googleapis.com and font-src https://fonts.gstatic.com
• Only with Voice: 'wasm-unsafe-eval' in script-src, and a Permissions-Policy that allows the microphone for your own origin (microphone=(self))

Content-Security-Policy: script-src 'self' 'nonce-{NONCE}' https://widget.onetwoagent.com;
  style-src 'self' 'nonce-{NONCE}'; connect-src 'self' https://api.onetwoagent.com wss://api.onetwoagent.com https://widget.onetwoagent.com;
  img-src 'self' https://widget.onetwoagent.com https://*.supabase.co data: blob:

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.

// Use the guarded helper in step 5 for initial login as well.
await refreshWidgetIdentity()

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.

invalidateWidgetIdentity() // step 5: invalidates pending fetches and calls reset()

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

let identityEpoch = 0
let pendingIdentity = null

// Call from existing logout/user/workspace-change hooks BEFORE fetching again.
function invalidateWidgetIdentity() {
  identityEpoch += 1
  pendingIdentity = null
  window.OneTwoAgent.reset()
}

function refreshWidgetIdentity() {
  if (!currentUserIsAuthenticated()) return Promise.resolve('signed_out')
  if (pendingIdentity) return pendingIdentity
  const epoch = identityEpoch
  const scope = currentAuthenticatedScopeKey() // from your existing auth state
  const request = (async () => {
    const response = await fetch('/api/onetwoagent/identity', {
      credentials: 'include', cache: 'no-store',
    })
    if (response.status === 401) return 'signed_out'
    if (!response.ok) return
    const { token } = await response.json()
    if (epoch !== identityEpoch || !currentUserIsAuthenticated()
      || scope !== currentAuthenticatedScopeKey()) return
    await window.OneTwoAgent.identify(token)
  })().catch(() => { /* retry only on the next natural trigger */ })
  pendingIdentity = request
  void request.finally(() => {
    if (pendingIdentity === request) pendingIdentity = null
  })
  return request
}
// The Widget asks when it holds a customer's identity and needs a fresh token. If that session ended
// (in another tab, or it expired), put the Widget back to anonymous instead of leaving it waiting.
window.addEventListener('otw:identity:required', () => {
  void refreshWidgetIdentity().then((outcome) => {
    if (outcome === 'signed_out') window.OneTwoAgent.reset()
  })
})

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.

invalidateWidgetIdentity() // before the user/workspace switch
// After the new authenticated scope is active:
await refreshWidgetIdentity()

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

Signed account snapshots are available in production. Extend the existing server identity exchange with a small customer-visible projection. The browser still calls identify(token). This snapshot describes observed state; it is not a live database lookup.

• Resolve externalUserId and the authorized active workspace from your existing server session. Never accept them, or account facts, directly from the browser request body.
• Add accountContext with schemaId saas_support_v1, version 1, scope.workspaceId, observedAt, expiresAt and facts. Unknown fields are rejected, including nested fields.
• Snapshot lifetime is at most 5 minutes from observedAt; observedAt cannot be in the future. The normal identity token lifetime remains 15 minutes. accountContextExpiresAt in the exchange response reports the earlier account deadline.
• The complete signed snapshot is limited to 2,048 UTF-8 bytes, the identity token to 6,144 bytes and combined identity/conversation proof headers to 8,192 bytes.
• Optional facts: name, email, plan, accountStatus, subscriptionStatus, role, capabilities, usage, jobs, integrations and reasonCode. Missing facts mean unknown, not zero or false.
• Labels name/plan/role: 80 characters. Email: 180. capabilities: at most 12 identifiers of 64 characters. usage: at most 4 rows with metric, nonnegative used and nonnegative or null limit. jobs: at most 3 rows with id, type, state and optional reasonCode. integrations: at most 3 rows with kind, state and optional reasonCode.
• accountStatus: active/trial/restricted/suspended/closed. subscriptionStatus: trialing/active/past_due/cancelled/expired/none. Job state: pending/running/completed/failed/cancelled. Integration state: connected/disconnected/pending/error. reasonCode: at most 64 uppercase letters, digits or underscores, starting with a letter.

// These two helpers represent your application's existing authorization code.
const user = await getCurrentAuthenticatedUser(request)
if (!user) return new Response(null, { status: 401 })
const workspace = await getAuthorizedActiveWorkspace(request, user.id)
if (!workspace) return new Response(null, { status: 403 })
const observedAt = new Date()
const response = await fetch(apiBaseUrl + '/api/widget/identity/token', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer ' + process.env.ONETWOAGENT_WIDGET_IDENTITY_SECRET,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    externalUserId: user.id, name: user.name, email: user.email,
    accountContext: {
      schemaId: 'saas_support_v1', version: 1,
      scope: { workspaceId: workspace.id },
      observedAt: observedAt.toISOString(),
      expiresAt: new Date(observedAt.getTime() + 240_000).toISOString(),
      facts: {
        plan: workspace.customerVisiblePlanLabel,
        accountStatus: 'active', // map explicitly from your own status enum
        usage: [{ metric: 'imports', used: workspace.importsUsed, limit: workspace.importLimit }],
      },
    },
  }),
})
// Return token/expiresIn/expiresAt/accountContextExpiresAt only; Cache-Control: no-store.
// Handle upstream errors without reflecting secrets or raw account data.

Request a new snapshot after account changes and when otw:identity:required fires. Coalesce concurrent refreshes, and discard responses for an old user or workspace using the lifecycle example above.

• Call getWidgetIdentity().invalidate() (from @onetwoagent/integration/browser) in your existing logout or user/workspace-change hook, then getWidgetIdentity().refresh() after the new authenticated session is active. It coalesces refreshes, drops responses for an old user and answers otw:identity:required once per page. Without the package, the lifecycle example above does the same.
• A fresh proof for the same user and external workspace resumes that account conversation. A different user or workspace resolves a separate conversation; do not select conversation IDs yourself.
• Account proof stays only in Widget memory and accompanies every account Text/Talk request. It is not written to localStorage, URLs or analytics. Expired or missing proof requires refresh; an older stored snapshot is never substituted.
• reset() clears local account presentation and signals other tabs for the same Widget to reset. Your application still owns logout/session synchronization and must invalidate its own pending identity fetches in each tab.
• The conversation history token has a separate, longer lifetime. reset() does not revoke previously issued history tokens on the server. Account proof controls new account AI work and Talk playback; do not describe this as instant history-token revocation.
• Queued turns retain their original snapshot only until its expiry. Refresh does not retroactively authorize an old queued turn; after a refresh the user may send a new question.
• Within the same unexpired signed snapshot, the server can include up to 8 recent messages within its existing token budget (default 1,200 estimated tokens), with verified source and publication records. This helps the agent follow previously tried steps; current account facts still come only from the signed snapshot.
• Re-signing an identical snapshot preserves this bounded dialogue context. Changing any snapshot content or timestamp starts a new AI history boundary; dialogue continuity is not carried across that refresh. Inbox history remains durable. Long-term AI summaries, shared caches and raw replay captures stay disabled for account turns.
• The snapshot itself needs no database credentials or public tool registration. For current state, use the optional fresh lookup endpoint described above.

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