Tokens de acceso personal
Un token de acceso personal (PAT) es una credencial que usted mismo crea y pega. Sirve para la API REST de Waafir y los scripts, y para un asistente de IA que no puede iniciar sesión: la mayoría de los asistentes se conectan pegando la URL de Waafir e iniciando sesión, sin ningún token. En los servidores MCP de Waafir, cada solicitud lleva o bien una conexión creada al iniciar sesión, o bien un PAT válido. No existe acceso anónimo, y una sesión de navegador iniciada normal no se acepta en esta superficie (una solicitud autenticada por sesión se rechaza). Un PAT actúa como usted, dentro de su organización, limitado por el alcance y las salas de datos que elija al emitirlo.
Dónde emitir un token
Abra Complementos → Configuración → Tokens API. La página tiene tres partes: un formulario para emitir un token nuevo, la lista de sus tokens existentes (con una acción para revocarlos) y un fragmento de configuración listo para usar con el que conectar un asistente mediante un token.
Para emitir un token, rellene el formulario:
- Nombre — una etiqueta legible para reconocer el token más adelante (por ejemplo, "Claude Desktop – portátil"). Obligatorio.
- Alcance — lo que el token puede hacer. Consulte más abajo.
- Alcance de la sala de datos — deje marcada la opción Todas las salas de datos para que el token llegue a todas las salas de datos a las que usted tiene acceso, o desmárquela y seleccione salas de datos concretas para restringir el token solo a ellas.
- Vencimiento — la fecha a partir de la cual el token deja de funcionar. Rellenarlo es opcional, pero en la práctica no lo es: si lo deja en blanco, el token se emite con un vencimiento de 90 días. Consulte Vencimiento.
Alcances
Un token tiene uno de tres alcances, en orden creciente de autoridad:
| Alcance | Permite | Uso típico |
|---|---|---|
read | Listar y leer — salas de datos, carpetas, archivos, metadatos de archivos, búsqueda, URL de descarga y consulta de permisos; leer el texto extraído de un documento; leer los hilos de preguntas y respuestas de los inversores; comprobar el estado de un trabajo de supresión de datos, traducción o firma electrónica. | Un asistente de solo lectura que responde preguntas sobre una sala de datos. |
write | Todo lo que permite read, más las modificaciones: crear, renombrar, mover, eliminar y restaurar carpetas; cargar, renombrar, mover, eliminar y restaurar archivos, incluida la carga de una nueva versión de un archivo y la reversión a una anterior; iniciar la supresión de datos o la traducción de un documento; y crear, enviar, rechazar y anular sobres de firma electrónica. Enviar un sobre (o añadir firmantes a uno ya enviado) requiere además Enviar a personas fuera de tu organización, y su asistente le pide confirmación antes de enviarlo. Firmar (esign_sign) requiere además Firmar documentos, y también se confirma antes. | Un asistente que organiza o mantiene una sala de datos. |
admin | Todo lo que permite write, más las cuatro herramientas que conceden permisos: conceder o revocar el acceso de un usuario a archivos y salas de datos. Tenga en cuenta que las tres herramientas de lectura de permisos solo requieren read. | Un asistente que gestiona quién puede ver qué. |
El alcance es acumulativo: un alcance superior incluye todo lo que está por debajo. La referencia de herramientas de cada servidor indica el alcance mínimo que requiere cada herramienta.
Quién puede emitir cada alcance
Un token nunca puede tener más autoridad que la persona que lo emite:
readywritelos puede emitir cualquier miembro activo de su organización.adminsolo lo puede emitir un propietario o administrador de la organización. Si usted no es propietario ni administrador, la opciónadminno aparece en el selector de alcance.- Los inversores (y otros roles que no pertenecen al equipo de la operación) no pueden emitir tokens en absoluto.
Más allá de la emisión, las herramientas de permisos admin aplican un
segundo límite en el momento de la llamada: el propietario del token debe ser
él mismo administrador o gestor de la organización para que una concesión de
permisos tenga éxito. El alcance del token es el límite del token; el rol
del propietario es el límite de la persona, y una acción de administración
debe superar ambos — exactamente la regla que aplica la interfaz del producto.
No hay ninguna vía más permisiva a través de MCP que a través del producto.
Permitir que un token firme documentos
Para firmar se necesita un token con Firmar documentos activado. Lo elige
al crear el token en Complementos → Configuración, para un token write o
admin, de modo que solo un asistente en el que usted haya confiado pueda
firmar por usted. Crear un token ya le pide su código de dos factores cuando
tiene activada la autenticación de dos factores, por lo que esa comprobación
cubre todas las firmas que haga el token. La lista de tokens muestra Puede firmar en cada uno de esos tokens.
Su asistente le muestra primero los documentos, el firmante y los campos, y
solo firma cuando usted lo confirma. A un token sin Firmar documentos no se
le muestra esign_sign en su lista de herramientas, y se rechaza si la llama.
Los tokens creados antes de que existiera esta opción no pueden firmar: cree
uno nuevo con Firmar documentos activado.
Permitir que un token lea el contenido de los documentos
Leer un documento completo, o preguntar a la IA sobre documentos, requiere un token con Leer contenido de documentos activado. Lo elige al crear el token en Complementos → Configuración, con cualquier alcance. La lista de tokens muestra Contenido del documento en cada uno de esos tokens. Cubre:
get_file_text, el texto extraído completo de un documento;get_file_download_url, un enlace para descargar un archivo;esign_download_signed, un PDF firmado electrónicamente;- el enlace de descarga que devuelve
translate_file_statuspara una traducción terminada; GET /api/v1/files/{fileId}/content, los bytes del documento a través de la API REST;POST /api/viewer/token,POST /api/viewer/artifact-accessyPOST /api/viewer/artifact-access/unlock, que generan el token o la cookie del visor con los que el visor de documentos del producto transmite un documento;- las herramientas de IA cuya pregunta o entrada escribe usted, ya que una
respuesta puede repetir lo que dice un documento:
dataroom_ask,dataroom_draft_answer,dataroom_compare_filesydataroom_generate_update; POST /api/v1/chat, la misma respuesta de IA a través de la API REST;- el
quotede cada dato que devuelveGET /api/v1/facts.
Un token sin esta opción recibe el rechazo de esas herramientas
(GRANT_REQUIRED) y de esas rutas REST (PAT_GRANT_REQUIRED), y
translate_file_status devuelve el estado con
download_withheld_reason: content_grant_required en lugar de un enlace.
GET /api/v1/facts y dataroom_list_facts devuelven cada dato sin su
quote, con value recortado a 20 palabras y value_truncated establecido.
El token puede seguir listando y buscando, y leer el resumen de un documento
con get_file_metadata o dataroom_summarise_file. Los tokens creados antes
de que existiera esta opción no pueden leer el contenido de los documentos:
cree uno nuevo con Leer contenido de documentos activado. Los tokens de
servicio no se ven afectados.
Cada token puede obtener como máximo 10 enlaces de descarga por minuto. Por
encima de eso, get_file_download_url se rechaza (RATE_LIMITED) y
translate_file_status devuelve el estado con
download_withheld_reason: rate_limited; vuelva a pedirlo pasado un minuto.
Permitir que un token envíe a personas fuera de su organización
Crear un enlace para compartir, añadir un espectador de una instantánea,
invitar a un miembro del equipo o a un inversor, y ampliar o restablecer el
acceso de un inversor (dataroom_extend_investor_access,
dataroom_reinstate_investor_access) dan acceso a alguien fuera de su
organización, por lo que requieren un token con Enviar a personas fuera de tu organización activado (el mismo permiso que envía las actualizaciones
para inversores, las respuestas de preguntas y respuestas y las solicitudes de
firma electrónica). Lo elige al crear un token write o admin en
Complementos → Configuración. La lista de tokens muestra Puede enviar externamente en cada uno de esos tokens.
Su asistente le muestra primero a quién da acceso un enlace nuevo, la regla de NDA y el vencimiento, y solo lo crea cuando usted lo confirma. Revocar un enlace o un espectador no requiere ningún permiso.
El permiso también cubre dar a alguien ajeno a su equipo de la operación
(propietarios, administradores y miembros) acceso, o más acceso, a una sala o
a un documento. "Ajeno" significa cualquier persona que no sea un miembro
activo del equipo de la operación de la organización de la sala: inversores,
invitados, personas con una invitación pendiente y miembros de otra
organización. Sin el permiso, un token recibe un rechazo (GRANT_REQUIRED en
MCP) para:
- una concesión de lectura o descarga a una de esas personas:
set_file_permissions,dataroom_set_folder_permissions,dataroom_bulk_set_file_permissions; - eliminar una denegación de esa persona, lo que restablece su acceso:
revoke_file_permission,dataroom_revoke_folder_permission,dataroom_bulk_revoke_file_permissions; - el acceso a la sala para esa persona, en cualquier nivel:
invite_user_to_dataroom; - cambiar el rol de un miembro cuyo rol actual no es del equipo de la
operación, lo que lo asciende:
dataroom_team_change_member_role; - un cambio de inversor que amplía el acceso:
dataroom_set_investor_permissionsde espectador a descargador, desactivar el NDA, o activar la supervisión o las actualizaciones.
Las denegaciones, el fin de una concesión y las concesiones a su equipo de la operación no requieren el permiso. No se cubre el contenido colocado donde una persona ya tiene acceso (cargar, mover, publicar). Adjuntar un NDA de firma inversora que esa firma haya firmado no requiere el permiso.
El mismo permiso se aplica a estas llamadas REST realizadas con un token de acceso personal:
POST /api/share-links(crear un enlace) yPOST /api/snapshots/{id}/viewersse rechazan con403 PAT_GRANT_REQUIREDsin él;POST /api/investors/invite(crea un enlace personal y lo envía por correo electrónico) se rechaza del mismo modo;PATCH /api/investors/{id}/extendyPATCH /api/investors/{id}/access(restablecer a un inversor o aprobar una solicitud de acceso) se rechazan del mismo modo; revocar a un inversor (DELETE /api/investors/{id}/access) no requiere el permiso;POST /api/team,POST /api/v1/teamyPOST /api/team/resend(una invitación al equipo envía por correo electrónico un enlace para unirse) se rechazan del mismo modo;PATCH /api/share-links/{id}se rechaza para cualquier modificación de la configuración de acceso de un enlace (activarlo, su modo, dominios, vencimiento o NDA, tanto si la modificación los amplía como si los restringe); desactivar un enlace siempre está permitido;GET /api/share-linksresponde sin elurlni eltokende cada enlace, marcados conurlWithheld: true, con unurlWithheldReasonque indica el motivo;POST /api/v1/grantsse rechaza para una concesión de lectura o descarga a alguien ajeno al equipo de la operación;DELETE /api/v1/grants/{id}se rechaza cuando la concesión es la denegación de esa persona;PATCH /api/v1/team/{id}se rechaza cuando el rol actual del miembro no es del equipo de la operación.
Estas comprobaciones leen la ruta tal como la enruta el servidor, de modo que
una barra final o un carácter codificado con porcentaje no las elude. Una ruta
que no se puede decodificar, o que contiene un segmento ./.. o una /
codificada dentro de un segmento, no puede asociarse a ninguna de las llamadas
que cubre un permiso. Así, un token de acceso personal al que le falte
cualquier permiso por solicitud —este,
Leer contenido de documentos o
Leer análisis de participación—
tiene todas esas rutas rechazadas con 403 PAT_PATH_MALFORMED, sea cual sea
la llamada.
Los tokens creados antes de que existiera este permiso no lo tienen, por lo
que pierden estas llamadas hasta que usted cree un nuevo token write o
admin con la opción activada. Un token read no puede tener este permiso.
Permitir que un token lea los análisis de participación
Leer análisis de participación permite a un token leer quién vio qué documentos, cuándo y durante cuánto tiempo: las herramientas de participación y los datos de participación de la lista de inversores. Actívelo solo para un asistente que deba ver esa información. Cualquier alcance puede tenerlo.
El mismo permiso se aplica a las lecturas de actividad REST:
GET /api/v1/activity (el flujo de actividad y auditoría de la organización),
/api/v1/activity/rollups, /api/v1/activity/engagement,
/api/v1/activity/engagement/documents y
/api/v1/activity/engagement/document/pages. Sin él, un token de acceso
personal se rechaza con 403 PAT_GRANT_REQUIRED. Los tokens de servicio y las
sesiones iniciadas no se ven afectados.
Los tokens creados antes de que existieran estas opciones no tienen ninguna: cree uno nuevo con la opción activada.
Restringir un token a salas de datos concretas
De forma predeterminada, un token puede llegar a todas las salas de datos a las que tiene acceso su propietario. Desmarcar Todas las salas de datos y seleccionar salas concretas restringe el token a esa lista permitida: cualquier llamada a una herramienta que haga referencia a una sala de datos fuera de la lista se rechaza, y un token restringido ni siquiera ve los nombres de las salas de datos que no puede abrir. Úselo para dar a un cliente de IA acceso a una operación sin exponer el resto de su cartera.
Vencimiento
Todos los tokens vencen. No existe ningún PAT perpetuo: un token que nunca vencía era precisamente el hallazgo de seguridad que este comportamiento viene a cerrar, porque una credencial olvidada sigue siendo válida para siempre. Establecer una fecha de vencimiento hace que el token deje de funcionar después de esa fecha: una solicitud con un token vencido se rechaza exactamente igual que una con uno revocado, con HTTP 401.
- Si deja el campo en blanco, obtiene 90 días, contados desde el momento en que se emite el token. En blanco significa usar el valor predeterminado, no no vencer nunca.
- Si establece una fecha, se respeta exactamente, hasta un máximo de 365 días desde la emisión.
- Si pide más de 365 días, la solicitud se rechaza, en lugar de acortarse sin aviso: la emisión nunca le devuelve un token de vida más corta de lo que pidió sin decírselo. Una fecha en el pasado se rechaza del mismo modo.
Por eso, si una integración debe seguir funcionando, establezca el vencimiento a conciencia y anote en su calendario un recordatorio para sustituir el token antes de que caduque: un campo en blanco detendrá esa integración sin aviso unos tres meses después de configurarla. No existe ninguna acción de renovación ni de rotación sobre un token existente, ni ningún aviso antes de que venza: sustituir uno significa emitir un token nuevo, actualizar la configuración de su cliente y revocar el antiguo. A la inversa, un vencimiento corto es exactamente lo adecuado para un token que emite para una tarea puntual.
La lista de tokens de Complementos → Configuración muestra el vencimiento de cada token, para que pueda ver cuáles están a punto de caducar.
La visualización única
Cuando emite un token, el valor en bruto — empieza por waafir_pat_ — se
muestra una sola vez, justo después de su creación. Waafir nunca almacena
el token en bruto, solo un hash unidireccional de él, por lo que no se puede recuperar ni volver a mostrar.
- Cópielo ahora y péguelo directamente en la configuración de su cliente. El panel de visualización tiene un botón para copiar.
- Si lo pierde, no puede recuperarlo: revoque ese token y emita uno nuevo.
- Trátelo como una contraseña: concede su alcance a cualquiera que lo tenga.
Después de la visualización, la lista de tokens solo muestra un breve
prefijo no secreto (por ejemplo waafir_pat_ab12…), para que pueda
distinguir sus tokens sin que el secreto pueda recuperarse.
Revocar un token
En la lista de tokens de Complementos → Configuración, use la acción Revocar junto a cualquier token. La revocación es inmediata: la siguiente solicitud que use el token se rechaza. Revoque un token en cuanto se pierda un dispositivo, se marche un contratista o simplemente ya no necesite el acceso. Los tokens revocados siguen visibles en la lista (marcados como revocados) para conservar el registro de lo que existió; nunca pueden reactivarse.
Cuando un token termina por sí solo
Un token actúa a través de su pertenencia a la organización, por lo que termina cuando termina esa pertenencia. No necesita revocarlo usted mismo cuando:
- Abandona la organización o un administrador le elimina de ella. Todos los tokens que tiene en esa organización se revocan en ese momento. Los tokens que tiene en otras organizaciones siguen funcionando.
- Un administrador de Waafir elimina su cuenta. Sus tokens en todas las organizaciones se revocan.
- Un administrador de Waafir elimina la organización. Todos sus tokens se revocan, incluidos sus tokens de servicio.
Estas revocaciones son permanentes. Que vuelvan a invitarle, o que se restablezca su cuenta o la organización, no recupera un token: emita uno nuevo.
Un token de servicio pertenece a la organización, no al administrador que lo creó, por lo que sigue funcionando cuando ese administrador se marcha. Solo revocarlo, o eliminar la organización, lo termina antes de tiempo.
El historial de tokens en el registro de auditoría
Cada token emitido o revocado escribe una fila en el registro de auditoría de la organización: quién lo hizo, el nombre, el alcance, los permisos y el vencimiento del token, a cuántas salas de datos está limitado y por qué se revocó (por su propietario, porque terminó una pertenencia o porque se eliminó una cuenta o una organización). El token en sí, su hash y su prefijo nunca se registran. Las filas aparecen en el registro completo de actividad, no en el resumen del panel.
Si Waafir no puede registrar un token nuevo en el registro de auditoría, el token no se emite y verá "The token wasn't created because we couldn't record it. Try again."
Siguiente paso: configure su cliente con el token que acaba de emitir.