Identity verification

​

Why use it

• Nobody can chat as one of your users. Keloa only accepts identity that your backend signed with a secret only you and Keloa know. There is no unsigned way to identify a visitor.
• Your team knows who they’re talking to. The context drawer shows the user ID, the profile and any extra attributes your site sends.
• Conversations follow the user. A signed-in user sees their own conversations in the widget on every browser and device.
• The AI can use the verified email. Tools that look up contact data by email (Shopify orders, and TRONVoice invoices, quotes and subscriptions) use it on that user’s own conversations, and a TRONVoice link your team made from that user’s conversation also counts for email written from that verified address.

​

How it works

1. A user signs in to your site or app.
2. Your server creates a token for that user: a JSON Web Token (JWT) with their user ID and profile, signed with HS256 and your secret.
3. Your page passes the token to the widget with Keloa('identify', { getToken }): a function that fetches it from your own endpoint. The token is never part of the page’s HTML.
4. The widget sends the token with every request. Keloa verifies the signature, the expiry and the audience, then links the conversation to that user’s contact.
5. When the token expires or Keloa rejects it, the widget calls getToken() for a fresh one.
6. When the user signs out, your page calls Keloa('logout'), the widget forgets them in that browser, and your other open tabs reload.

​

Before you start

• A backend with signed-in users. The token must be signed on your server. A static site or a page without accounts can’t use identity verification.
• HTTPS. With identity verification on, only https pages of your allowed sites, on the standard https port (443), can show the widget. For development, localhost, 127.0.0.1, *.test and *.localhost also work over http and on any port.
• The right role. Only workspace owners and admins can create or revoke secrets and change the mode. See Members & roles.
• The widget installed. Your site already loads the embed snippet. See Web widget.

​

Set it up in Keloa

​

Sign the token on your server

1. Build the header: alg HS256, typ JWT and kid set to your key ID.
2. Build the claims: user_id, aud (your agent ID), iat, exp and the profile fields you want to share.
3. Encode the header and the claims as JSON, then base64url without padding (no trailing =).
4. Sign <header>.<claims> with your secret and append the base64url signature.

<?php

// KELOA_IDENTITY_SECRET, KELOA_IDENTITY_KEY_ID and KELOA_AGENT_ID live in your
// server's environment, never in the browser.
function keloa_base64url(string $data): string
{
    return rtrim(strtr(base64_encode($data), '+/', '-_'), '=');
}

function keloa_identity_token(array $user): string
{
    $secret = (string) getenv('KELOA_IDENTITY_SECRET');
    $keyId = (string) getenv('KELOA_IDENTITY_KEY_ID');
    $agentId = (string) getenv('KELOA_AGENT_ID');
    if ($secret === '' || $keyId === '' || $agentId === '') {
        throw new RuntimeException('Keloa identity verification is not configured.');
    }

    $now = time();
    $header = ['alg' => 'HS256', 'typ' => 'JWT', 'kid' => $keyId];
    $claims = [
        'user_id' => (string) $user['id'],
        'aud' => $agentId,
        'iat' => $now,
        'exp' => $now + 1800, // 30 minutes, never more than 24 hours
        'email' => $user['email'],
        'email_verified' => $user['email_verified'] === true, // only when you proved ownership
        'name' => $user['name'],
    ];

    $flags = JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE | JSON_THROW_ON_ERROR;
    $signingInput = keloa_base64url(json_encode($header, $flags))
        .'.'.keloa_base64url(json_encode($claims, $flags));
    $signature = hash_hmac('sha256', $signingInput, $secret, true);

    return $signingInput.'.'.keloa_base64url($signature);
}

<?php

// config/services.php
//   'keloa' => [
//       'agent_id' => env('KELOA_AGENT_ID'),
//       'identity_key_id' => env('KELOA_IDENTITY_KEY_ID'),
//       'identity_secret' => env('KELOA_IDENTITY_SECRET'),
//       'identity_ttl' => (int) env('KELOA_IDENTITY_TTL', 1800),
//       // The loader URL from your embed snippet, without "?agent=…".
//       'loader_url' => env('KELOA_LOADER_URL'),
//   ],

namespace App\Services\Keloa;

use App\Models\User;
use Illuminate\Contracts\Auth\MustVerifyEmail;
use RuntimeException;
use Throwable;

class KeloaIdentityToken
{
    /** Keloa refuses tokens that live longer than a day. */
    private const MAX_TTL_SECONDS = 86400;

    public static function isConfigured(): bool
    {
        return filled(config('services.keloa.identity_secret'))
            && filled(config('services.keloa.identity_key_id'))
            && filled(config('services.keloa.agent_id'));
    }

    /**
     * A token for the user, or null when there is no user or signing fails.
     * Never throws, so a missing setting can't break your pages: the widget
     * just stays anonymous.
     */
    public function tokenIfAllowed(?User $user): ?string
    {
        if ($user === null || ! static::isConfigured()) {
            return null;
        }

        try {
            return $this->tokenFor($user);
        } catch (Throwable $e) {
            report($e);

            return null;
        }
    }

    public function tokenFor(User $user): string
    {
        if (! static::isConfigured()) {
            throw new RuntimeException('Keloa identity verification is not configured.');
        }

        $now = now()->getTimestamp();

        $claims = [
            'user_id' => (string) $user->getKey(),
            'aud' => (string) config('services.keloa.agent_id'),
            'iat' => $now,
            'exp' => $now + $this->ttl(),
            'email' => $user->email,
            // Only true for an address the user confirmed. This is only correct if
            // your app clears email_verified_at whenever the email changes: see
            // "When users change their email" below.
            'email_verified' => $user instanceof MustVerifyEmail && $user->hasVerifiedEmail(),
            'name' => $user->name,
            'language' => app()->getLocale(),
            // Optional: 'company' => ['id' => (string) $user->team_id, 'name' => $user->team?->name],
            // Optional: 'attributes' => ['plan' => $user->plan],
        ];

        $header = ['alg' => 'HS256', 'typ' => 'JWT', 'kid' => (string) config('services.keloa.identity_key_id')];
        $signingInput = $this->encode($header).'.'.$this->encode($claims);
        $signature = hash_hmac('sha256', $signingInput, (string) config('services.keloa.identity_secret'), true);

        return $signingInput.'.'.$this->base64Url($signature);
    }

    /** Never longer than the user's session, nor than the day Keloa accepts. */
    private function ttl(): int
    {
        $sessionSeconds = max((int) config('session.lifetime', 120), 1) * 60;

        return max(60, min((int) config('services.keloa.identity_ttl', 1800), $sessionSeconds, self::MAX_TTL_SECONDS));
    }

    private function encode(array $data): string
    {
        return $this->base64Url(json_encode($data, JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE | JSON_THROW_ON_ERROR));
    }

    private function base64Url(string $value): string
    {
        return rtrim(strtr(base64_encode($value), '+/', '-_'), '=');
    }
}

import { createHmac } from 'node:crypto';

// KELOA_IDENTITY_SECRET stays on your server, never in the browser.
const b64url = (value) => Buffer.from(value).toString('base64url'); // no padding

export function keloaIdentityToken(user) {
  const { KELOA_IDENTITY_SECRET, KELOA_IDENTITY_KEY_ID, KELOA_AGENT_ID } = process.env;
  if (!KELOA_IDENTITY_SECRET || !KELOA_IDENTITY_KEY_ID || !KELOA_AGENT_ID) {
    throw new Error('Keloa identity verification is not configured.');
  }

  const now = Math.floor(Date.now() / 1000);
  const header = { alg: 'HS256', typ: 'JWT', kid: KELOA_IDENTITY_KEY_ID };
  const claims = {
    user_id: String(user.id),
    aud: KELOA_AGENT_ID,
    iat: now,
    exp: now + 30 * 60, // 30 minutes, never more than 24 hours
    email: user.email,
    email_verified: user.emailVerified === true,
    name: user.name,
  };

  const input = `${b64url(JSON.stringify(header))}.${b64url(JSON.stringify(claims))}`;
  const signature = createHmac('sha256', KELOA_IDENTITY_SECRET).update(input).digest('base64url');

  return `${input}.${signature}`;
}

import base64
import hashlib
import hmac
import json
import os
import time


def _b64url(data: bytes) -> str:
    return base64.urlsafe_b64encode(data).rstrip(b"=").decode()  # no padding


def keloa_identity_token(user) -> str:
    # On your server only, never in the browser.
    secret = os.environ["KELOA_IDENTITY_SECRET"]
    key_id = os.environ["KELOA_IDENTITY_KEY_ID"]
    agent_id = os.environ["KELOA_AGENT_ID"]

    now = int(time.time())
    header = {"alg": "HS256", "typ": "JWT", "kid": key_id}
    claims = {
        "user_id": str(user.id),
        "aud": agent_id,
        "iat": now,
        "exp": now + 30 * 60,  # 30 minutes, never more than 24 hours
        "email": user.email,
        "email_verified": user.email_verified is True,
        "name": user.name,
    }

    signing_input = ".".join(
        _b64url(json.dumps(part, separators=(",", ":")).encode()) for part in (header, claims)
    )
    signature = hmac.new(secret.encode(), signing_input.encode(), hashlib.sha256).digest()

    return signing_input + "." + _b64url(signature)

require "base64" # Ruby 3.4 and later: add gem "base64" to your Gemfile
require "json"
require "openssl"

module KeloaIdentity
  module_function

  def b64url(data)
    Base64.urlsafe_encode64(data, padding: false)
  end

  # KELOA_IDENTITY_SECRET stays on your server, never in the browser.
  def token_for(user)
    secret = ENV.fetch("KELOA_IDENTITY_SECRET")
    key_id = ENV.fetch("KELOA_IDENTITY_KEY_ID")
    agent_id = ENV.fetch("KELOA_AGENT_ID")

    now = Time.now.to_i
    header = { alg: "HS256", typ: "JWT", kid: key_id }
    claims = {
      user_id: user.id.to_s,
      aud: agent_id,
      iat: now,
      exp: now + 30 * 60, # 30 minutes, never more than 24 hours
      email: user.email,
      email_verified: user.email_verified == true,
      name: user.name
    }

    signing_input = "#{b64url(header.to_json)}.#{b64url(claims.to_json)}"
    signature = OpenSSL::HMAC.digest("SHA256", secret, signing_input)

    "#{signing_input}.#{b64url(signature)}"
  end
end

package keloa

import (
	"crypto/hmac"
	"crypto/sha256"
	"encoding/base64"
	"encoding/json"
	"errors"
	"os"
	"strconv"
	"time"
)

type User struct {
	ID            int64
	Email         string
	EmailVerified bool
	Name          string
}

func b64url(data []byte) string {
	return base64.RawURLEncoding.EncodeToString(data) // no padding
}

// IdentityToken signs a Keloa identity token. The secret stays on your server.
func IdentityToken(user User) (string, error) {
	secret := os.Getenv("KELOA_IDENTITY_SECRET")
	keyID := os.Getenv("KELOA_IDENTITY_KEY_ID")
	agentID := os.Getenv("KELOA_AGENT_ID")
	if secret == "" || keyID == "" || agentID == "" {
		return "", errors.New("keloa identity verification is not configured")
	}

	now := time.Now().Unix()
	header, err := json.Marshal(map[string]string{"alg": "HS256", "typ": "JWT", "kid": keyID})
	if err != nil {
		return "", err
	}
	claims, err := json.Marshal(map[string]any{
		"user_id":        strconv.FormatInt(user.ID, 10),
		"aud":            agentID,
		"iat":            now,
		"exp":            now + 30*60, // 30 minutes, never more than 24 hours
		"email":          user.Email,
		"email_verified": user.EmailVerified,
		"name":           user.Name,
	})
	if err != nil {
		return "", err
	}

	input := b64url(header) + "." + b64url(claims)
	mac := hmac.New(sha256.New, []byte(secret))
	mac.Write([]byte(input))

	return input + "." + b64url(mac.Sum(nil)), nil
}

​

When users change their email

• Breeze’s ProfileController and the current Laravel starter kits clear it on every email change.
• Fortify’s and Jetstream’s UpdateUserProfileInformation action only clears it when your User implements MustVerifyEmail. Jetstream’s default User doesn’t.
• Custom profile forms, admin tools, imports, seeders and social sign-in code can set email_verified_at or leave it in place.

​

Add a token endpoint

• only answers a signed-in session, and answers 401 (not a redirect to your login page) otherwise;
• accepts POST with your framework’s CSRF protection, so only your own pages can call it;
• sends no CORS headers, and stays out of any CORS configuration that reflects the request’s origin with credentials;
• is rate limited, for example to 30 requests per minute per user;
• returns the token as JSON ({"token": "…"}) with Cache-Control: no-store, private;
• doesn’t keep an idle session alive: while a signed-in chat is open, the widget calls it in the background whenever its token expires, so these calls must not count as user activity or extend the session, and the endpoint answers 401 once the user has been idle longer than your timeout.

<?php

// routes/web.php (the web group gives you the session and CSRF protection)
Route::post('/keloa/identity-token', KeloaIdentityTokenController::class)
    ->middleware(['auth', 'throttle:30,1']) // a JSON request from a guest gets 401, not a redirect
    ->name('keloa.identity-token');

// app/Http/Controllers/KeloaIdentityTokenController.php
namespace App\Http\Controllers;

use App\Services\Keloa\KeloaIdentityToken;
use Illuminate\Http\JsonResponse;
use Illuminate\Http\Request;

class KeloaIdentityTokenController extends Controller
{
    public function __invoke(Request $request, KeloaIdentityToken $tokens): JsonResponse
    {
        $token = $tokens->tokenIfAllowed($request->user());
        abort_if($token === null, 503);

        return response()
            ->json(['token' => $token])
            ->header('Cache-Control', 'no-store, private');
    }
}

// Mount this behind your session middleware and your CSRF middleware.
app.post('/keloa/identity-token', (req, res) => {
  res.set('Cache-Control', 'no-store, private');
  if (!req.user) {
    return res.status(401).json({ error: 'unauthenticated' });
  }
  res.json({ token: keloaIdentityToken(req.user) });
});

from flask import jsonify
from flask_login import current_user


@app.post("/keloa/identity-token")  # protected by Flask-WTF's CSRFProtect
def keloa_identity_token_endpoint():
    if not current_user.is_authenticated:
        response = jsonify(error="unauthenticated")
        response.status_code = 401
    else:
        response = jsonify(token=keloa_identity_token(current_user))
    response.headers["Cache-Control"] = "no-store, private"
    return response

# config/routes.rb
#   post "/keloa/identity-token", to: "keloa_identity_tokens#create"

class KeloaIdentityTokensController < ApplicationController
  # ApplicationController's protect_from_forgery checks the X-CSRF-Token header.
  def create
    response.headers["Cache-Control"] = "no-store, private"
    return head :unauthorized unless current_user

    render json: { token: KeloaIdentity.token_for(current_user) }
  end
end

// Wrap this handler in your CSRF middleware (for example gorilla/csrf).
func IdentityTokenHandler(w http.ResponseWriter, r *http.Request) {
	w.Header().Set("Cache-Control", "no-store, private")
	if r.Method != http.MethodPost {
		http.Error(w, "method not allowed", http.StatusMethodNotAllowed)
		return
	}

	user, ok := currentUser(r) // your own session lookup
	if !ok {
		http.Error(w, "unauthenticated", http.StatusUnauthorized)
		return
	}

	token, err := keloa.IdentityToken(user)
	if err != nil {
		http.Error(w, "unavailable", http.StatusServiceUnavailable)
		return
	}

	w.Header().Set("Content-Type", "application/json")
	json.NewEncoder(w).Encode(map[string]string{"token": token})
}

​

Hand the token to the widget

<script>
  window.Keloa=typeof window.Keloa==='function'?window.Keloa:(function(o){var f=function(){f.q.push(arguments)};f.q=(o&&o.q)||[];f.init=function(c){f.q.push(c)};return f})(window.Keloa);

  Keloa('identify', {
    // Called right away, and again whenever the token expires or is rejected.
    getToken: function () {
      var csrf = document.querySelector('meta[name="csrf-token"]');
      return fetch('/keloa/identity-token', {
        method: 'POST',
        credentials: 'same-origin',
        cache: 'no-store',
        headers: { Accept: 'application/json', 'X-CSRF-Token': csrf ? csrf.content : '' }
      }).then(function (response) {
        var type = response.headers.get('Content-Type') || '';
        if (!response.ok || response.redirected || type.indexOf('application/json') === -1) throw new Error('Not signed in');
        return response.json();
      }).then(function (body) {
        if (!body || typeof body.token !== 'string' || body.token === '') throw new Error('No token');
        return body.token;
      });
    }
  });
</script>

​

When the user signs out

<script>
  window.Keloa=typeof window.Keloa==='function'?window.Keloa:(function(o){var f=function(){f.q.push(arguments)};f.q=(o&&o.q)||[];f.init=function(c){f.q.push(c)};return f})(window.Keloa);

  (function () {
    if (window.keloaSignOut) return; // once per tab, also when the script runs again
    var channel = null;
    try { channel = new BroadcastChannel('keloa-identity'); } catch (e) { channel = null; }
    var reload = function () { window.Keloa('logout'); window.location.reload(); };

    // Another tab signed out: forget the user here too, and reload this tab.
    if (channel) { channel.onmessage = function (e) { if (e.data === 'logout') { reload(); } }; }
    window.addEventListener('storage', function (e) { if (e.key === 'keloa-logout') { reload(); } });

    // This tab signs out: forget the user, then tell every other tab.
    window.keloaSignOut = function () {
      window.Keloa('logout');
      if (channel) { channel.postMessage('logout'); return; }
      try { localStorage.setItem('keloa-logout', String(Date.now())); } catch (e) {}
    };
  })();
</script>

• Sign-out with a full page load (a form POST and a redirect): call it on the page the user lands on. Flash a value on the redirect, for example keloa_logout, and only call it when that value is present.
• Single-page apps (React, Vue, Inertia, Livewire wire:navigate, Turbo): always call it when the user signs out, right after your sign-out request succeeds. The widget lives on across page swaps, so nothing else tells it. Do this even when your sign-out also loads a new page.

​

Laravel Blade partial

• identifies signed-in users with getToken alone, so no token is ever part of the HTML;
• signs the widget out when the user signs out, and reloads every other open tab that showed a signed-in page;
• reloads a page the browser restores from its back/forward cache after it identified someone;
• loads the widget.

{{-- resources/views/partials/keloa-widget.blade.php --}}
@if (config('services.keloa.agent_id') && config('services.keloa.loader_url'))
@php
    $keloaSignedIn = auth()->check() && \App\Services\Keloa\KeloaIdentityToken::isConfigured();
    $keloaRefreshUrl = route('keloa.identity-token', absolute: false);
    $keloaLoaderUrl = config('services.keloa.loader_url').'?agent='.urlencode((string) config('services.keloa.agent_id'));
@endphp
<script>
    (function () {
        window.Keloa=typeof window.Keloa==='function'?window.Keloa:(function(o){var f=function(){f.q.push(arguments)};f.q=(o&&o.q)||[];f.init=function(c){f.q.push(c)};return f})(window.Keloa);

        @auth
        window.__keloaEverSignedIn = true;
        @endauth

        // Once per tab: when the user signs out in any tab, forget them here and
        // reload, and never let a back/forward-cache restore revive a signed-in page.
        if (!window.__keloaSignOut) {
            var channel = null;
            try { channel = new BroadcastChannel('keloa-identity'); } catch (e) { channel = null; }
            var forget = function () { window.__keloaIdentified = false; window.Keloa('logout'); };
            // A tab that showed a signed-in page reloads, which also drops the copies
            // of earlier pages that Livewire or Turbo keep in memory for Back.
            var reload = function () { forget(); if (window.__keloaEverSignedIn) { window.location.reload(); } };
            window.__keloaSignOut = function () {
                forget();
                if (channel) { channel.postMessage('logout'); return; }
                try { localStorage.setItem('keloa-logout', String(Date.now())); } catch (e) {}
            };
            if (channel) { channel.onmessage = function (e) { if (e.data === 'logout') { reload(); } }; }
            window.addEventListener('storage', function (e) { if (e.key === 'keloa-logout') { reload(); } });
            // Sticky: sign-out clears __keloaIdentified before the page is cached.
            window.addEventListener('pageshow', function (e) { if (e.persisted && window.__keloaEverIdentified) { window.location.reload(); } });
        }

        @if (session('keloa_logout'))
        window.__keloaSignOut();
        @endif

        @if ($keloaSignedIn)
        window.__keloaIdentified = true;
        window.__keloaEverIdentified = true;
        window.Keloa('identify', {
            // The only way the token reaches the page: never render it into the HTML.
            getToken: function () {
                var csrf = document.querySelector('meta[name="csrf-token"]');
                return fetch(@json($keloaRefreshUrl), {
                    method: 'POST',
                    credentials: 'same-origin',
                    cache: 'no-store',
                    headers: { 'Accept': 'application/json', 'X-CSRF-TOKEN': csrf ? csrf.getAttribute('content') : '' }
                }).then(function (r) {
                    var type = r.headers.get('Content-Type') || '';
                    if (!r.ok || r.redirected || type.indexOf('application/json') === -1) { throw new Error('Keloa token refresh failed'); }
                    return r.json();
                }).then(function (body) {
                    if (!body || typeof body.token !== 'string' || body.token === '') { throw new Error('Keloa token refresh failed'); }
                    return body.token;
                });
            }
        });
        @else
        // The session behind an earlier identify in this tab is gone (the user
        // signed out in a single-page app, or it expired): sign out everywhere.
        if (window.__keloaIdentified) { window.__keloaSignOut(); }
        @endif

        var s = document.createElement('script');
        s.src = @json($keloaLoaderUrl);
        if (document.readyState === 'complete') { document.body.appendChild(s); }
        else { window.addEventListener('load', function () { document.body.appendChild(s); }); }
    })();
</script>
@endif

Auth::guard('web')->logout();
$request->session()->invalidate();
$request->session()->regenerateToken();

return redirect('/')->with('keloa_logout', true);

​

Claims reference

​

Header

​

Claims

• Text that is too long is cut to the limit: a name, company or attribute string is shortened, not dropped.
• A value that is invalid, such as an email that isn’t a valid address or is longer than 255 characters, or a phone in the wrong format, is dropped and never stored. The rest of the token still counts.
• Control characters and invisible formatting characters in text are replaced with a space, and repeated spaces are collapsed.

​

How Keloa uses the claims

• Contact. The first time Keloa sees a user, it joins an existing contact only when email_verified is true and the address exactly matches a contact email Keloa already trusts, and that contact doesn’t already belong to another signed-in user or to an anonymous website visitor. Otherwise it creates a new contact. Your team can still merge the two contacts later.
• Profile sync. On later visits, Keloa fills empty fields and updates a field when your site’s value changed since the last sync. A change a teammate made stays until your site sends a different value.
• Email. A verified address becomes the contact’s email when the contact has none. It also replaces an address the visitor typed into the conversation (which Keloa never trusted), unless another signed-in user shares the contact, and it replaces the address this user’s own token verified before when your site sends a new verified one. Keloa never replaces an address your team entered or one that arrived by email. An address sent without email_verified: true only fills an empty email, is not trusted and never replaces an address.
• Company. A company needs a name. With an id, users with the same id share one company that Keloa created for that ID from this agent. With only a name, Keloa creates a company for that user alone. Keloa never joins a company your team created, or any existing company by name.
• Attributes. They appear in the Verified user block in the inbox. A key that matches the key of a contact custom field fills that field. null never clears a value. When several signed-in users share a contact, the AI and macros on a website conversation only use a synced field when that conversation’s own user sent that value.

​

JavaScript API reference

​

identify options

​

Security model

​

What Keloa guarantees

• Only signed identity counts. Keloa accepts identity only from a token signed with one of the agent’s active secrets. There is no unsigned identify call; Keloa('identify') without a token does nothing.
• Every request is checked. The token travels with every widget request, and Keloa verifies the signature, expiry and audience each time.
• A rejected token is never downgraded. A token that fails verification is never treated as an anonymous visitor. Keloa answers 401 with a reason code and the widget asks your page for a fresh token.
• One agent, one set of users. Secrets belong to one agent, and Keloa keys each user on the agent plus the user ID. A token for one agent can never speak for another agent’s users.
• Conversations stay with their owner. A signed-in user’s conversations are only visible to that user. Anonymous visitors can never read them, and an anonymous visitor only reaches the conversations they started in that browser, even after a teammate merges contacts. The one exception is a website conversation from before this release, when Keloa didn’t yet record which browser started a conversation: it is open to every visitor on its contact, so after a contact merge another visitor’s browser can open it, until your team merges it with a newer conversation of the visitor who wrote it, which ties it to that visitor (see Identity matching and merging). A website conversation only merges with conversations of the same visitor or the same signed-in user: Keloa refuses to merge it with anyone else’s conversation or with another channel’s, so another person’s messages, subject and tags never reach it. A website conversation that a merge made before that rule mixed with another person’s or another channel’s conversation is never shown in the widget again, and the AI, emails and flows leave out what Keloa can’t attribute to the visitor (see Website conversations merged before the rule).
• Anonymous visitors are kept apart per workspace. The widget gives each browser a separate random visitor ID for every Keloa workspace, also when several shops share one host (for example shop-a.example-host.com and shop-b.example-host.com). Keloa never shows that ID to your team: the contact card says Anonymous website visitor, and the inbox and data exports only hold a keyed code that opens nothing. So no team can use what it sees to open a visitor’s conversation with another workspace. Visitors who chatted before this change start a new anonymous conversation once; their earlier conversations stay in your inbox. The ID they used before is retired for good, in every workspace: a browser tab that still runs the widget from before the change can’t start or open a conversation with it, and chats again once the page reloads.
• Only your sites can show the widget. With verification on, Keloa tells browsers that only your allowed origins, over https on the standard port, may embed the widget. Another site can’t frame it to push its own user’s token into a visitor’s conversation.
• Secrets are protected. Secrets are stored encrypted and shown only once. Only owners and admins can create or revoke them, and every change is recorded in the audit log. Keloa never logs tokens. Revoking a secret cuts off every token signed with it at once, including live-update connections that are already open (see Rotate or revoke a secret).
• Contact data needs a verified email. AI tools only use an email your site verified on that same user’s conversations. On an anonymous website conversation the AI never uses the contact’s email address for customer data: the Shopify order lookup asks the visitor for the email on the order, and TRONVoice data only comes through a link a teammate made from that same conversation. See Tools.
• Anonymous conversations only use what the visitor said there. On an anonymous website conversation, the AI, flow messages, conditions and action values, macros and the widget’s own messages only use what the visitor said in that conversation, or in their own earlier conversations your team merged into it: a name, email address or phone number they typed in the chat or the contact form. {{contact.email}} and {{contact.phone}} render empty unless the visitor typed that address or number there. A name, company or language that your team, an email or a merge put on the contact, and every contact and company custom field, your team’s included, count as unknown; the language follows the visitor’s own messages. On a signed-in user’s conversation, the name, company, language and custom fields are the ones your site signed for that user, and the email and phone also show the verified email and the phone your site signed. An AI-drafted email on an anonymous conversation only greets the visitor by a name they gave there. On a conversation from before this release that is still open to every visitor on its contact (see above), what was typed there shows to whoever opens it.
• Email replies stay with the visitor. Your team can answer a website conversation by email only at an address shown to be the visitor’s: one they typed in that conversation (in a message or the contact form) or in the contact form of one of their own earlier conversations your team merged into it, the verified email your site signed for that signed-in user, an address whose owner already emailed into that conversation, or an address your team corrected on a contact that wasn’t merged with another contact. Otherwise the reply goes to the chat. An email sent from the conversation only quotes and carries the visitor’s own messages and subject, and only names the visitor by a name they gave. See Replying to conversations. See Messages & actions and Conditions.

​

What your site must guarantee

• Sign only for authenticated users. Create tokens on your server for the user of the current session, never for an ID the browser sends you.
• Don’t sign for impersonated users. When your staff use a “log in as user” or impersonation feature, don’t sign a token for the impersonated user. Otherwise their messages are stored as that user’s conversations, follow the user to their devices, and unlock the user’s data through the AI.
• Keep the secret secret. Store it in your environment or secrets manager. Never ship it to a browser, a mobile app or a repository. Revoke it at once if it leaks.
• Use a stable user ID. Use an ID that never changes and is never reused for another person. Don’t use the email address as the user ID.
• Be honest about email_verified. Send true only when the user proved they own the address, for example with a confirmation link. If users can change their email, send false until they confirm the new address, and require their current password for the change (see When users change their email). A wrong true lets someone take over another person’s contact and data (see the warning under Claims reference).
• Keep tokens short-lived. A token is a bearer credential: anyone who holds it can chat as that user until it expires, and a live-update connection opened with it keeps receiving that conversation’s new replies for up to 13 minutes after its exp (the 60-second clock-skew allowance, plus up to 12 minutes until the connection’s channel moves on). Use 15–60 minutes and getToken to refresh, and never let a token outlive the user’s session on your site.
• Serve your site over HTTPS.
• Protect the token endpoint. Require a session, use POST with CSRF protection, send no CORS headers, rate-limit it and answer 401 when signed out.
• Watch the scripts on signed-in pages. Any script on those pages can call your token endpoint and read the token. Keep third-party tags off them where you can, and protect them against XSS, for example with a Content Security Policy.
• Never put a token in a page. Pass getToken only, never token, so a page restored from the back/forward cache, a single-page framework’s memory, a CDN or a full-page cache can’t sign the widget in again. Send Cache-Control: no-store, private on the token endpoint, so no cache ever keeps its answer.
• Keep tokens out of URLs, storage and logs. Don’t put them in query strings, localStorage, analytics or error reports.
• Call Keloa('logout') on every sign-out, also in single-page apps, and reload your other open tabs (see When the user signs out). Logout only clears the browser tab that calls it; it doesn’t invalidate tokens you already issued.

​

Rotate or revoke a secret

• in Optional mode, signed-in users chat anonymously until you create a new secret and update your site;
• in Required mode, nobody can chat until you do.

​

Staging and development

• Never copy a secret of your production agent, or its key ID, to staging or development.
• Never sign a token for a production user from staging or development.
• Don’t add staging or development hosts to your production agent’s Allowed origins. Add them to the separate agent instead.

​

What your team sees

• Signed in on your site or app during this chat, with when Keloa last verified the user.
• User ID — the user_id your site signed.
• Every attribute your site sent. The first 4 are shown; click Show all to see the rest.

• On a signed-in user’s conversation it says Verified: the person is signed in on your site, and a link made there applies to their conversations, and on email only to mail from the address your site verified for them.
• On an anonymous conversation it says Not verified: a link made there applies to that conversation only, and only while that one visitor is the only one writing in it. It never applies to the contact’s email or other conversations, also not after a contact merge. Before linking, Keloa asks you to confirm with Link anyway, because the AI can then share that client’s invoices, quotes and subscriptions in the conversation. The AI stops using the link once the conversation has messages from anyone else: another visitor, messages merged in from another channel or another contact, or any email reply, including one from the address owner. Keloa refuses to link from a conversation that already has such messages, and from a mixed conversation (see Website conversations merged before the rule).
• On a website conversation from before Keloa told website visitors apart, the panel says a link can’t be made there. Keloa refuses the link, and a link made from it earlier no longer gives the AI any data. Link the client from the email conversation instead, or ask the visitor to sign in or start a new chat.

​

Guests, sign-in, sign-out and devices

​

Troubleshooting

​

FAQ

​

Related