Access Tags

Overview

Some content is not for everyone: member-only documents, region-specific material, paid-tier resources. Access Tags lets one chatbot serve different audiences safely. You put a tag on a knowledge item, and from that moment the item is invisible to every visitor — except those whose page presents that tag, signed by your own server. The restriction is enforced in our retrieval query, before the AI model is involved at all. A visitor without the tag cannot extract the content by clever prompting, because for them it was never retrieved in the first place.

How It Works

1. You tag knowledge items - on the Access Tags page or directly through the API; untagged items keep working for everyone
2. Your server signs each visitor's tags - when a logged-in member loads your page, your back end decides their entitlements and signs them with a secret key only you hold
3. The widget sends the signed claim - it travels with every chat message; the browser only transports it and cannot alter it without breaking the signature
4. We verify and filter - a valid signature unlocks items with matching tags; a missing, tampered or expired claim means the visitor gets public content only

Setting It Up

Turn the feature on at the Access Tags page in your dashboard — a signing secret is generated for you. Keep it on your server only; anyone who has it can mint valid claims.

Tag your content either on the same page, or when pushing items through the API:

POST /api/v1/knowledge/text/
{
  "title": "Members-only price list",
  "content": "...",
  "website_id": "123",
  "access_tags": ["premium"]
}

Then have your server print the signed claim next to the widget snippet. The message to sign is the comma-separated tag list, joined with a pipe and the expiry time when you use one:

<?php
$tags    = "members,premium";          // this visitor's entitlements
$expires = time() + 3600;              // unix seconds, optional but recommended
$sig     = hash_hmac("sha256", $tags . "|" . $expires, $SECRET);
?>
<script>
window.Asyntai = window.Asyntai || {};
window.Asyntai.accessTags = "<?php echo $tags; ?>";
window.Asyntai.accessTagsExpires = "<?php echo $expires; ?>";
window.Asyntai.accessTagsSignature = "<?php echo $sig; ?>";
</script>

The same signature in Node.js and Python:

// Node.js
const crypto = require("crypto");
const sig = crypto.createHmac("sha256", SECRET)
                  .update(tags + "|" + expires).digest("hex");

# Python
import hmac, hashlib
sig = hmac.new(SECRET.encode(), f"{tags}|{expires}".encode(),
               hashlib.sha256).hexdigest()

Without an expiry, sign just the tag string on its own. With one, a claim stops working the moment it passes — useful when entitlements can be revoked, since the visitor has to reload a page you control to get a fresh claim.

Tag Logic

An item's tags combine as AND: the item is retrievable only when every tag on it appears in the visitor's claim. A visitor's claim may carry as many entitlements as you like, and matching happens across all of them at once.

AND is deliberate. With any-of matching, adding a second tag to an item would widen who can see it, so narrowing a document to two groups would in fact publish it to both of them in full. With all-of matching, every tag you add can only restrict further, so a mistake fails in the safe direction.

Expressing “any of”

Leave the dimension off the item. If every visitor's claim carries their region, then a document with no region tag is available to all regions, while its other tags still apply. So an item tagged only premium means “any region, premium subscribers only”.

For a genuine cross-dimension choice — say north-with-basic or south-with-premium, and nothing else — add the item twice with one combination each, or give both audiences a shared tag your server includes in their claims.

Limits

• Up to 20 tags per knowledge item
• Up to 50 tags in a single visitor's claim
• 50 characters per tag; commas and vertical bars are not allowed, since the claim is a comma-separated string

Changing tags later

Tags can be replaced on an existing item without re-uploading it. The change applies to the next question asked — the content itself is not re-processed.

POST /api/v1/knowledge/<id>/tags/
{
  "access_tags": ["premium"]
}

Send an empty list to make an item public again. You can also edit tags by hand on the Access Tags page in your dashboard.

What Is Guaranteed

• Server-side enforcement - the filter runs inside our database query at retrieval; tagged items are absent from the AI's context for unauthorised visitors, so there is nothing to leak
• Fail closed everywhere - no signature, wrong signature, expired claim, feature switched off, plan downgraded: in every one of these cases the visitor gets public content only, never more
• The browser cannot forge access - editing the tags in developer tools breaks the signature; only your server holds the secret
• Your entitlement logic stays yours - we never learn how you decide who gets which tag; we only verify that your server said so

Good To Know

• Access Tags is authorisation, User Context is personalisation - use User Context to tell the AI about the member; use Access Tags to control which knowledge the AI may draw on
• Website crawl content is always public - it comes from your public website, so there is nothing to restrict; tags apply to text, file and API items
• Tags on an item combine as AND - see Tag Logic above; every tag on the item must be present in the visitor's claim
• Regenerating the secret invalidates every old claim - do it if the secret may have leaked, then update your pages to sign with the new one
• Tag names are up to you - up to 20 per item, 50 characters each, no commas or pipes; they never appear in the visitor-facing chat