Access Tags

Descripción general

No todo el contenido es para todos: documentos solo para socios, material específico de una región, recursos de niveles de pago. Access Tags permite que un solo chatbot atienda a distintos públicos con seguridad. Pones una etiqueta en un elemento de conocimiento y, desde ese momento, el elemento es invisible para cualquier visitante — excepto aquellos cuya página presenta esa etiqueta, firmada por tu propio servidor. La restricción se aplica en nuestra consulta de recuperación, antes de que el modelo de IA participe siquiera. Un visitante sin la etiqueta no puede extraer el contenido con preguntas ingeniosas, porque para él nunca se recuperó.

Cómo funciona

1. Etiquetas elementos de conocimiento - en la página de Access Tags o directamente por la API; los elementos sin etiquetas siguen funcionando para todos
2. Tu servidor firma las etiquetas de cada visitante - cuando un socio conectado carga tu página, tu back-end decide sus permisos y los firma con una clave secreta que solo tú posees
3. El widget envía la credencial firmada - viaja con cada mensaje del chat; el navegador solo la transporta y no puede alterarla sin romper la firma
4. Verificamos y filtramos - una firma válida desbloquea los elementos con etiquetas coincidentes; una credencial ausente, manipulada o caducada significa que el visitante solo recibe contenido público

Cómo configurarlo

Activa la función en la página de Access Tags de tu panel — se genera una clave de firma para ti. Guárdala solo en tu servidor; quien la tenga puede crear credenciales válidas.

Etiqueta tu contenido en esa misma página o al enviar elementos mediante la API:

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

Después haz que tu servidor imprima la credencial firmada junto al fragmento del widget. El mensaje a firmar es la lista de etiquetas separadas por comas, unida con una barra vertical a la hora de caducidad cuando uses una:

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

La misma firma en Node.js y 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()

Sin caducidad, firma solo la cadena de etiquetas. Con caducidad, una credencial deja de funcionar en cuanto vence — útil cuando los permisos pueden revocarse, porque el visitante tiene que recargar una página que tú controlas para obtener una credencial nueva.

Qué está garantizado

• Aplicación del lado del servidor - el filtro se ejecuta dentro de nuestra consulta a la base de datos durante la recuperación; los elementos etiquetados no llegan al contexto de la IA para visitantes no autorizados, así que no hay nada que filtrar
• Fail-closed en todos los casos - sin firma, firma incorrecta, credencial caducada, función desactivada, plan rebajado: en todos ellos el visitante solo recibe contenido público, nunca más
• El navegador no puede falsificar el acceso - editar las etiquetas en las herramientas de desarrollo rompe la firma; solo tu servidor posee la clave
• Tu lógica de permisos sigue siendo tuya - nunca sabemos cómo decides quién recibe qué etiqueta; solo verificamos que tu servidor lo afirmó

Conviene saber

• Access Tags es autorización, User Context es personalización - usa User Context para contarle a la IA quién es el socio; usa Access Tags para controlar qué conocimiento puede usar la IA
• El contenido rastreado de la web siempre es público - procede de tu sitio público, así que no hay nada que restringir; las etiquetas se aplican a elementos de texto, archivos y API
• A un visitante le basta una etiqueta coincidente - un elemento con dos etiquetas está disponible para un visitante que tenga cualquiera de las dos
• Regenerar la clave invalida todas las credenciales antiguas - hazlo si la clave pudo filtrarse y actualiza después tus páginas para firmar con la nueva
• Los nombres de las etiquetas los eliges tú - hasta 20 por elemento, 50 caracteres cada una, sin comas ni barras verticales; nunca aparecen en el chat que ve el visitante