One key for every customer you serve

Before you start

• A Sonela workspace. A platform key works on every plan, and counts as one key.
• Data that already keeps your customers apart. Connect your database in the dashboard, say that several organisations share it, and name the column that says whose each row is: only tables that carry it are offered to the assistant. Or start from written material alone — manuals, help pages — which needs no column at all.

Your signing secret

In the dashboard, under Integration › Vouched sessions, create your signing secret. It starts sk_ and is shown once: keep it in your server's settings and never in a page. Creating a new one later keeps the old one working for 24 hours, so you can deploy it without an outage.

One platform key

Under Widget › Keys & snippet, create a key and switch on One key for every organisation my platform serves. Choose the data source and list the sites your product runs on; if each customer has a subdomain of its own, one entry such as https://*.yourapp.com covers them all. The key (pk_…) is public by design: it sits in your page source and opens nothing on its own.

Your server signs

For each signed-in person, a path on your own site — /api/sonela-voucher, say — answers {"visitorToken": "…"}: a token signed HS256 with your signing secret, carrying

• aud: widget-vouch
• exp: a few minutes out — Sonela refuses one more than 8 hours ahead
• pk: your platform key
• end_tenant: your id for the customer this person belongs to, one string or whole number of up to 128 characters
• email, if you like: where the documents this person asks for are sent

const crypto = require('node:crypto');

// Your signing secret (sk_...). It stays on your server.
const secret = process.env.SONELA_SIGNING_SECRET;
const publicKey = 'pk_...'; // your platform key

const base64url = (value) => Buffer.from(value).toString('base64url');

function sonelaToken(customerId) {
  const header = { alg: 'HS256', typ: 'JWT' };
  const payload = {
    aud: 'widget-vouch',
    exp: Math.floor(Date.now() / 1000) + 300, // five minutes
    pk: publicKey,
    end_tenant: customerId, // the customer this person belongs to
  };
  const signingInput =
    base64url(JSON.stringify(header)) + '.' +
    base64url(JSON.stringify(payload));
  const signature = crypto
    .createHmac('sha256', secret)
    .update(signingInput)
    .digest('base64url');
  return signingInput + '.' + signature;
}

// GET /api/sonela-voucher, behind your own sign-in:
//   response.json({ visitorToken: sonelaToken(signedInUser.customerId) });

The dashboard's Integration › Code for your site has the same signer in C#, Python and PHP; add the pk and end_tenant lines.

One tag on your pages

<script src="https://api.sonela.ai/sonela.js"
        data-key="pk_..."
        data-vouch-url="/api/sonela-voucher"
        defer></script>

Before each session the assistant asks that path for a fresh token, sending the person's own cookies, so the path must be on the same origin as the page. If your pages and your server live at different addresses, write the token into the tag as data-visitor-token when the page is rendered instead — that is how Sonela's own dashboard carries its help assistant.

Signing out

The assistant keeps its session in the page's memory and nothing on the device, so a sign-out that ends in a page load starts the next person afresh. A single-page app that signs out without one calls window.Sonela.destroy(); the assistant comes back with the next page load.

What Sonela holds to

• The customer comes from your signed token alone, never from the page, and a platform key opens no session without one.
• Every query is rewritten to that customer before it runs, and a platform key is refused on a data source that does not keep customers apart.
• Every open session is checked against its key at each question: delete the key and every session it opened ends at its next one.
• Each customer draws on a share of the rate limit of its own, so one busy customer cannot slow the rest. The month's question allowance is your workspace's, shared by all of them.
• Of your API lookups, a customer's session is offered only those that name the customer, or that you marked as answering the same for everyone.
• Usage lists each customer by the id you signed, from its first question. There is nothing to create per customer.

The security brief sets out the separation in full, and where it stops.

Customers come and go

• A new customer: sign its id. Nothing changes in Sonela.
• A customer who leaves: stop signing its id. No new session opens for them; a token already issued lasts until it expires, so keep it to minutes, and an open session for at most 30 minutes.
• A new domain: add it to the key's sites. The key stays the same, so no page changes.
• A key per customer still works too, if you prefer it: each one names its customer when you create it.