Introduction to Custom Sign In

Give your users a familiar login (Google, Apple, your own SSO), then hand Knoon a short-lived credential so the Chat Box works under your identity.

What you’ll build

1. A login page you host (e.g., https://service.example.com/login)

2. A backend endpoint that exchanges your user identity for a Knoon credential using your Organization ID + API Key

3. A postMessage hand-off back to the opener (the page where the Chat Box runs)

Prerequisites

• Your Knoon Organization ID and API Key (server-side only).

• A domain you control for cookies, e.g. example.com → shared cookie domain .example.com.

• The Chat Box ID (from Knoon > Chat > Chat Boxes > select a Chat Box).

Step 1 — Enable Custom Sign-In in Knoon (Chat Box)

1. Go to Knoon > Chat > Chat Boxes > Create/Modify Chat Box.

2. In “Sign in”, toggle “Enable”.

3. Set “Custom Sign-in URL” to your hosted login page, e.g. https://service.example.com/login

4. (Optional) Keep “Block Sign Out” enabled if you prefer to manage sign-out within your own system. This is recommended when using a shared cookie domain, as seamless sign-out from your website will also sign the user out of Knoon. You’ll need to clear authentication cookies manually when the user signs out from your site.

Tip: Your login page should know which Chat Box started the flow (pass chatBoxId as a query string or via window features).

Step 2 — Frontend: your login page (popup)

After your user authenticates in your system, call your backend to fetch a Knoon credential. Then postMessage back to the opener and close the popup.

Example

// After your user is authenticated in YOUR system:
const response = await $axios.post(
  '/api/knoon/credentials',          // your backend endpoint
  { chatBoxId }                      // same ID as the running Chat Box
)

if (response.data?.data) {
  const data = response.data.data
  // Only send to a strict allowlisted origin you control:
  window.opener?.postMessage(
    data,                             // Encrypted payload
    'https://example.com'             // EXACT origin of the opener
  )
  window.close()
}

Step 3 — Backend: exchange your user for a Knoon credential

From your server, call Knoon’s Credentials API using Basic Auth (organizationId as the username and apiKey as the password).

⚠️ WARNING

Never expose apiKey to the frontend. Keep them on the server.

Example

import axios from 'axios'

export async function getKnoonCredentials(req, res) {
  try {
    const { user } = req                        // your logged-in user context
    const { chatBoxId } = req.body

    const resp = await axios.post(
      'https://api.knoon.ai/v1/credentials/login',
      {
        email: user.email,
        externalId: user.uid,
        photoURL: user.photoURL,
        displayName: user.displayName,
        chatBoxId
      },
      {
        auth: {
          username: process.env.KNOON_ORG_ID,   // organizationId
          password: process.env.KNOON_API_KEY   // apiKey
        },
        timeout: 10000
      }
    )

    const data = resp?.data?.data
    return res.status(200).send({
      status: data ? 'ok' : 'bad_request',
      data: {
        ...data,
        // Use a shared parent domain so cookies work across subdomains:
        // e.g., '.example.com'
        domain: '.example.com'
      }
    })
  } catch (err) {
    console.error('Knoon credential exchange failed:', err?.response?.data || err)
    return res.status(500).send({ status: 'server_error' })
  }
}

NOTE

If the Chat Box runs on www.example.com and your login page is service.example.com, a parent domain cookie .example.com allows both to read it.

Step 5 — End-to-end sequence

1. User clicks “Sign in” within the Chat Box > popup opens https://service.example.com/login?chatBoxId=...

2. Your login page authenticates the user with your own authentication system.

3. Your login page calls your backend /api/knoon/credentials with { chatBoxId }.

4. Your backend calls Sign in with organizationId + apiKey.

5. Your backend returns the credential { jwt, chatBoxId, ... , domain: '.example.com' }.

6. Your login page postMessages that payload Sign in and closes.

7. The opener stores the credential in cookies > Chat Box is now signed in.