How Cookies Work in Custom Sign-In

When using Custom Sign-In with Knoon, your system authenticates the user and then stores short-lived Knoon credentials as cookies. These cookies allow the Chat Box to operate under your user’s session. This guide explains how cookies are set and managed after obtaining credentials from your backend.

1. Overview

The flow works as follows:

1. Frontend (your app) calls your own backend to request a Knoon credential.

2. Backend securely calls the Knoon API using your Organization ID and API Key.

3. The backend returns a short-lived credential (jwt, expiresAt, domain).

4. Frontend stores these values in cookies (scoped to your shared domain, e.g. .example.com).

5. The Chat Box automatically picks up these cookies and authenticates the user.

2. Backend – Requesting Credentials

Your backend acts as the bridge between your user and Knoon’s authentication system.

It receives a chatBoxId from the frontend and exchanges your user’s info for a Knoon credential.

const response = await $axios.post(`${$config.public.BACKEND_FUNCTION_URL_PREFIX}/knoon/credentials`, {
  chatBoxId
})

On your backend:

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: req.body.chatBoxId
}, {
  auth: {
    username: process.env.KNOON_ORG_ID,
    password: process.env.KNOON_API_KEY
  }
})

const data = resp?.data?.data
res.status(200).send({
  status: data ? 'ok' : 'bad_request',
  data: {
    ...data,
    domain: '.example.com’
  }
})

IMPORTANT

• Never expose your Organization ID or API Key to the frontend.

• Always call the Knoon API from your server.

• The returned credential is short-lived and scoped to the Chat Box.

3. Frontend – Storing Cookies

Once the backend returns the credential, store it in cookies so the Chat Box can detect and use it automatically.

if (response.data?.data) {
  const data = response.data.data
  if (data?.jwt && data?.expiresAt) {
    const expiresAt = new Date(data.expiresAt)
    const { domain } = data
    Cookies.set(`knoon_contact_session_jwt_${chatBoxId.value}`, data.jwt, { 
      expires: 1/24, // 1 hour
      domain
    })
    Cookies.set(`knoon_contact_session_jwt_expires_at_${chatBoxId.value}`, expiresAt.getTime(), { 
      expires: 1/24,
      domain
    })
    Cookies.set(`knoon_contact_session_jwt_domain_${chatBoxId.value}`, domain, { 
      expires: 1/24,
      domain
    })
  }
}

Explanation of Each Cookie

NOTES

• Domain: Use a parent domain (e.g., .example.com) so all subdomains (e.g., app.example.com, support.example.com) can read the same cookies.

• Expiry: Short-lived (1 hour)

4. Reading Cookies (Optional)

You can read these cookies later if you need to verify whether a user session exists or refresh expired credentials.

const jwt = Cookies.get(`knoon_contact_session_jwt_${chatBoxId}`)
const expiresAt = Cookies.get(`knoon_contact_session_jwt_expires_at_${chatBoxId}`)

5. Signing Out

When users sign out from your system, you must also clear Knoon cookies to prevent session reuse.

Cookies.remove(`knoon_contact_session_jwt_${chatBoxId}`, { domain: '.example.com’ })
Cookies.remove(`knoon_contact_session_jwt_expires_at_${chatBoxId}`, { domain: '.example.com’ })
Cookies.remove(`knoon_contact_session_jwt_domain_${chatBoxId}`, { domain: '.example.com’ })

TIP

Enable “Block Sign Out” in the Knoon Chat Box settings if you’re using shared cookies. This ensures sign-out is fully controlled by your system, providing seamless single sign-on and sign-off.