Access Tags

Visão Geral

Nem todo o conteúdo é para todos: documentos só para membros, material específico de uma região, recursos de níveis pagos. O Access Tags permite que um único chatbot sirva públicos diferentes em segurança. Coloca uma etiqueta num elemento de conhecimento e, a partir desse momento, o elemento fica invisível para qualquer visitante — exceto aqueles cuja página apresenta essa etiqueta, assinada pelo seu próprio servidor. A restrição é aplicada na nossa consulta de recuperação, antes de o modelo de IA sequer participar. Um visitante sem a etiqueta não consegue extrair o conteúdo com perguntas engenhosas, porque para ele nunca chegou a ser recuperado.

Como funciona

1. Etiqueta elementos de conhecimento - na página Access Tags ou diretamente pela API; os elementos sem etiquetas continuam a funcionar para todos
2. O seu servidor assina as etiquetas de cada visitante - quando um membro autenticado carrega a sua página, o seu back-end decide os direitos dele e assina-os com uma chave secreta que só você possui
3. O widget envia a credencial assinada - segue com cada mensagem do chat; o navegador apenas a transporta e não a pode alterar sem quebrar a assinatura
4. Nós verificamos e filtramos - uma assinatura válida desbloqueia os elementos com etiquetas correspondentes; uma credencial ausente, adulterada ou expirada significa que o visitante só recebe conteúdo público

Como configurar

Ative a funcionalidade na página Access Tags do seu painel — é gerada uma chave de assinatura para si. Guarde-a apenas no seu servidor; quem a tiver pode criar credenciais válidas.

Etiquete o conteúdo na mesma página, ou ao enviar elementos através da API:

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

Depois faça o seu servidor imprimir a credencial assinada junto ao snippet do widget. A mensagem a assinar é a lista de etiquetas separadas por vírgulas, unida por uma barra vertical à hora de expiração quando usar uma:

<?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>

A mesma assinatura em Node.js e 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()

Sem expiração, assine apenas a cadeia de etiquetas. Com expiração, uma credencial deixa de funcionar assim que o prazo passa — útil quando os direitos podem ser revogados, porque o visitante tem de recarregar uma página que você controla para obter uma credencial nova.

O que está garantido

• Aplicação do lado do servidor - o filtro corre dentro da nossa consulta à base de dados na recuperação; para visitantes não autorizados, os elementos etiquetados estão ausentes do contexto da IA, pelo que não há nada para fugir
• Fail-closed em todo o lado - sem assinatura, assinatura errada, credencial expirada, funcionalidade desligada, plano descido: em qualquer destes casos o visitante recebe apenas conteúdo público, nunca mais do que isso
• O navegador não pode forjar acesso - editar as etiquetas nas ferramentas de programador quebra a assinatura; só o seu servidor possui a chave
• A sua lógica de direitos continua sua - nunca sabemos como decide quem recebe que etiqueta; apenas verificamos que o seu servidor o afirmou

Bom saber

• Access Tags é autorização, User Context é personalização - use o User Context para contar à IA quem é o membro; use o Access Tags para controlar que conhecimento a IA pode usar
• O conteúdo rastreado do site é sempre público - vem do seu site público, pelo que não há nada a restringir; as etiquetas aplicam-se a elementos de texto, ficheiros e API
• Um visitante só precisa de uma etiqueta correspondente - um elemento com duas etiquetas fica disponível para um visitante que tenha qualquer uma delas
• Regenerar a chave invalida todas as credenciais antigas - faça-o se a chave puder ter fugido e atualize depois as suas páginas para assinarem com a nova
• Os nomes das etiquetas são escolha sua - até 20 por elemento, 50 caracteres cada, sem vírgulas nem barras verticais; nunca aparecem no chat visto pelos visitantes