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.

Lógica de etiquetas

Las etiquetas de un elemento se combinan con Y: el elemento solo se recupera cuando todas sus etiquetas aparecen en la credencial del visitante. La credencial de un visitante puede llevar tantos permisos como quieras, y la comparación se hace con todos a la vez.

El Y es deliberado. Con una comparación de «alguna», añadir una segunda etiqueta a un elemento ampliaría quién puede verlo, así que restringir un documento a dos grupos lo publicaría de hecho por completo a ambos. Con la comparación de «todas», cada etiqueta que añadas solo puede restringir más, de modo que un error cae del lado seguro.

Expresar «cualquiera de»

Deja la dimensión fuera del elemento. Si la credencial de cada visitante lleva su región, un documento sin etiqueta de región está disponible para todas las regiones, mientras sus demás etiquetas siguen aplicándose. Así, un elemento etiquetado solo con premium significa «cualquier región, solo suscriptores premium».

Para una elección real entre dimensiones — por ejemplo norte-con-básico o sur-con-premium, y nada más — añade el elemento dos veces con una combinación cada vez, o da a ambos públicos una etiqueta común que tu servidor incluya en sus credenciales.

Límites

• Hasta 20 etiquetas por elemento de conocimiento
• Hasta 50 etiquetas en la credencial de un mismo visitante
• 50 caracteres por etiqueta; no se permiten comas ni barras verticales, ya que la credencial es una cadena separada por comas

Cambiar las etiquetas más adelante

Las etiquetas se pueden reemplazar en un elemento existente sin volver a subirlo. El cambio se aplica a la siguiente pregunta — el contenido en sí no se reprocesa.

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

Envía una lista vacía para volver a hacer público un elemento. También puedes editar las etiquetas a mano en la página Access Tags de tu panel.

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
• Las etiquetas de un elemento se combinan con Y - consulta Lógica de etiquetas arriba; cada etiqueta del elemento debe estar presente en la credencial del visitante
• 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