En la documentación Tokens de API
Desarrolladores y agentes
Tokens de API
Un token de API permite a un agente de IA, a un script o a una herramienta trabajar con tus documentos sin conocer tu contraseña, solo con los derechos que le concedas. Un token nuevo no abre nada; puedes retirarlo cuando quieras.
Qué es un token de API
Un token es una larga cadena secreta que empieza por pgn_. El agente lo envía con cada solicitud a la API REST de Paginel (Authorization: Bearer pgn_…): Paginel reconoce entonces el token, no a una persona. Solo da acceso a lo que se le ha concedido.
Cada token lleva el nombre de su cliente (claude-code, chatgpt…). En el documento, el agente aparece con ese nombre (agent:claude-code): lo que escribe queda firmado y fechado en el historial, y se puede deshacer como cualquier otra cosa. Puedes pausarlo o excluirlo del documento, y revocar su token al instante.
Un token no puede crear otros tokens: solo una persona con sesión iniciada puede hacerlo. Paginel no llama por sí mismo a ningún modelo: el token sirve al agente que hayas elegido, en el proveedor que hayas elegido (véase Gestión de datos).
Crear uno
Hay dos lugares.
- Desde el documento, en línea en Paginel: el panel Agente (Insertar › Agente) y después Agente en línea; o haz clic derecho en un título, Conectar un agente a esta sección…. El diálogo propone primero el conector de Paginel; abre Para desarrolladores: un token (script, API) y después Dar acceso. Si un token activo, creado a mano, ya lleva el nombre del agente, Paginel le añade un derecho para este documento (o para la sección elegida); si no, crea el token con ese primer derecho y lo muestra una sola vez. Después, dos pasos: 1. pon el token en la variable
PAGINEL_TOKENde tu agente («Copiar token»); 2. «Copiar el texto para el agente». El texto copiado nunca contiene el token. - Desde Agentes y API, en tu espacio, en la parte plegada Para desarrolladores: «Nuevo token» y después, para cada token, «Añadir un derecho», «Renovar» o «Revocar».
Un token activo por nombre y por cuenta: se rechaza crear un segundo con el mismo nombre; renueva el primero o añádele un derecho. Tampoco se puede usar el nombre de una aplicación conectada. Un nombre se compone de letras, cifras, guiones y guiones bajos, 32 caracteres como máximo. Paginel no guarda el token en sí, solo su huella: un token perdido no se puede recuperar, se renueva.
Derechos: lo que abre el token
Un token no abre nada hasta que se le concede un derecho. Abre lo que abren en conjunto sus derechos vigentes; para un mismo documento, cuenta el derecho más amplio.
| Un derecho se compone de | A elegir |
|---|---|
| Un alcance | Un documento, una carpeta (los documentos que contiene en el momento de la petición) o todos tus documentos. Para un documento, puedes limitarlo a una sección. |
| Un nivel | Lectura: leer el documento. Comentario: leer y comentar. Edición: leer, comentar, escribir y cambiar el nombre; en una carpeta, también crear documentos en ella. |
| Una caducidad | 7, 30, 90 o 365 días, o ninguna; 30 días por defecto desde el documento. El token también tiene la suya, elegida de la misma lista. |
Un derecho de sección lo impone el núcleo del documento, no solo el token: Paginel inscribe al agente en el documento con la sección que se le asigna, y cualquier escritura fuera de ella se rechaza; el agente lee el resto. Si esa inscripción falla, no se crea ningún derecho.
Lo que un agente nunca puede hacer
- Eliminar un documento o moverlo de una carpeta a otra.
- Crear, renovar o revocar tokens.
- Escribir donde ninguna persona lo haya permitido: un agente escribe en las secciones que se le han confiado, o en todo el documento dentro de los límites de los derechos de su responsable, sean cuales sean los derechos de su token.
Retirar un acceso
Quitar un derecho corta el acceso a ese documento, o a esa sección, y nada más; revocar el token lo corta todo, al instante. En el documento, en Para desarrolladores: un token (script, API), Acceso a este documento enumera los agentes que tienen acceso (alcance, derechos, caducidad, último uso), con «Quitar»; solo la persona propietaria del documento ve esa lista.
Dónde poner el token
Entrega el token a tu agente mediante variables de entorno, tres en total:
PAGINEL_URL: la dirección de la plataforma, por ejemplohttps://paginel.com;PAGINEL_TOKEN: el token,pgn_…;PAGINEL_DOC: el identificador del documento, el final de su dirección…/d/<identificador>.
Terminalexport PAGINEL_URL="https://paginel.com"export PAGINEL_TOKEN="pgn_…"export PAGINEL_DOC="identificador-del-documento" Nunca en una dirección (las direcciones se guardan en registros), en un documento, en un comentario, en un repositorio de código ni en una conversación compartida. La SKILL le indica lo mismo al agente: enviar el token únicamente a PAGINEL_URL, y no mostrarlo, registrarlo ni escribirlo nunca.
Una primera llamada
Una vez definidas las variables, así es como se piden al agente sus instrucciones (quién es su responsable, dónde puede escribir) y después se lee el documento:
Terminalcurl -sS "$PAGINEL_URL/api/docs/$PAGINEL_DOC/instructions" \ -H "Authorization: Bearer $PAGINEL_TOKEN"curl -sS "$PAGINEL_URL/api/docs/$PAGINEL_DOC" \ -H "Authorization: Bearer $PAGINEL_TOKEN" Las instrucciones también dan las solicitudes al agente dejadas en el documento (el panel Agente, «Solicitudes al agente»: «Nueva solicitud…», o Insertar › Pedir al agente…), en el campo requests: el agente escribe en el pasaje correspondiente y después marca la solicitud como hecha. Todas las rutas se describen en openapi.json y en la SKILL (consulta «Enlaces» más abajo).
Claude Code: instalar la SKILL
Una SKILL es una carpeta de archivos que enseña al agente qué es Paginel, sus reglas y toda la API. La plataforma la sirve, pública y sin token, en una dirección con versión (/agent/v1/); sigue la evolución de la API y crece cuando Paginel gana funciones. Instálala, comprueba las huellas publicadas con ella y vuelve a instalarla después de una actualización:
TerminalB="$PAGINEL_URL/agent/v1"mkdir -p ~/.claude/skills/paginel/referencescd ~/.claude/skills/paginelcurl -fsS "$B/SKILL.md" -o SKILL.mdcurl -fsS "$B/references/api.md" -o references/api.mdcurl -fsS "$B/references/rules.md" -o references/rules.mdcurl -fsS "$B/references/markdown.md" -o references/markdown.mdcurl -fsS "$B/SHA256SUMS" -o SHA256SUMSshasum -a 256 -c SHA256SUMS La parte «Para desarrolladores» de la página Agentes y API también muestra esta instalación, con «Copiar el comando». El texto copiado desde un documento le pide al agente que use la skill paginel y, si no está instalada, que lea /agent/v1/SKILL.md y compruebe /agent/v1/SHA256SUMS. Consulta también Anthropic, Agent Skills.
La app de Claude y ChatGPT: el conector
En la aplicación de Claude (web, escritorio, móvil) y en ChatGPT, lo más sencillo es el conector de Paginel: lo autorizas una vez, para lo que elijas, sin copiar ningún token. La aplicación conectada aparece entonces en Agentes y API, en Aplicaciones conectadas, con «Lo que ve» y «Quitar el acceso». Consulta Conectar Claude o ChatGPT.
En Claude Desktop, la SKILL sigue siendo posible: sube paginel.zip en Personalizar › Skills (la carpeta paginel/ y sus cuatro archivos, sin ningún token). Según la documentación de Anthropic, el acceso a la red de una skill depende de la configuración de la aplicación: completo, parcial o nulo, según el usuario o el administrador (Anthropic, Skills overview); Paginel debe estar autorizado allí.
Una aplicación de escritorio no tiene necesariamente acceso a tus variables de entorno: tendrías que dar el token en la conversación, donde quedaría en el historial. Prefiere el conector; si no, elige un derecho restringido y una caducidad corta, y revoca el token después.
ChatGPT: un GPT con Actions
Sin el conector, la otra vía es un GPT personalizado con Actions: importa openapi.json como esquema y pon el token en los ajustes de autenticación de la acción (clave de API, tipo Bearer), no en el esquema. Según OpenAI, el secreto de una clave de API se cifra allí y el esquema se guarda aparte. Consulta OpenAI, Configuring actions in GPTs y GPT Action authentication; comprueba allí lo que permite tu plan.
Solo para ti. Según OpenAI, el acceso propio de cada persona pasa por OAuth: es lo que hace el conector. Un token de Paginel puesto en una Action es el tuyo: úsalo solo en un GPT privado, con un derecho restringido (un documento o una sección, una caducidad corta). Esas páginas no dicen qué ven las personas que usan un GPT compartido: por precaución, no pongas este token en un GPT que usen otros.
Un script u otro agente
Cualquier herramienta capaz de hacer peticiones HTTP puede llamar a la API con el token, como en el ejemplo anterior. openapi.json describe las rutas; la SKILL, escrita en inglés para los agentes, describe además las reglas de Paginel.
Buenas prácticas
Las cinco primeras son nuestras; las dos siguientes repiten lo que dicen los proveedores de agentes, con sus enlaces más abajo.
- Derechos restringidos. Un documento o una sección en lugar de todos tus documentos; «comentario» en lugar de «edición» cuando el agente no necesita escribir. Si el token se filtra, solo abrirá eso.
- Una vida corta. 30 días por defecto desde el documento; evita «sin caducidad».
- Un token por cliente: uno para Claude Code y otro para ChatGPT. Así sabes quién hizo qué, y puedes cortar uno sin tocar el otro.
- Renovar. «Renovar» crea un nuevo token con los mismos derechos; el anterior sigue válido durante 10 minutos, el tiempo necesario para cambiar la variable, y después se revoca.
- Vigilar y revocar. La lista muestra el último uso y la última dirección vista, truncada (la red, nunca el equipo completo). Tu espacio marca una «dirección inusual» cuando un token se usa desde una red distinta a la de la vez anterior; Paginel no envía correos electrónicos. A la menor duda, revoca.
- Ninguna credencial escrita en una skill. Anthropic clasifica como riesgo alto las credenciales escritas en una skill (acaban en el historial de Git y en la ventana de contexto) y pide variables de entorno o almacenes seguros. La SKILL de Paginel no contiene ningún token; una prueba lo comprueba.
- Instalar en lugar de leer cada vez. Anthropic desaconseja una skill que va a buscar sus instrucciones a una dirección (puede quedar comprometida si cambia lo que carga) y aconseja tratarla como un software que se instala, fijar las versiones y comprobar una huella. De ahí la SKILL instalada, en una dirección con versión, con sus
SHA256SUMS; leerla en la dirección solo es un último recurso. No contiene ningún script y solo envía el token aPAGINEL_URL.
Si un token se ha filtrado
Publicado en un repositorio, pegado en una conversación, visible en una captura de pantalla: revócalo de inmediato, desde Agentes y API. La lista indica cuándo y desde dónde se usó por última vez. Después crea otro token, con derechos igual de restringidos.
Referencia
| Asunto | Lo que hace Paginel |
|---|---|
| Formato | pgn_, seguido de 64 caracteres hexadecimales aleatorios y, después, 6 caracteres de suma de control (CRC32 en base 62, como los tokens de GitHub). Una suma incorrecta se rechaza sin consultar la base de datos; el formato antiguo, sin suma, sigue aceptándose. El prefijo y la suma permiten que una herramienta de detección de secretos reconozca un token de Paginel sin enviarlo a Paginel. |
| Límites | 20 tokens activos por cuenta, 100 derechos por token, 300 peticiones por minuto y por token. |
404 «Documento desconocido.» | El token es desconocido, está revocado o caducado, o no tiene ningún derecho vigente sobre ese documento. |
403 | El nivel del token no es suficiente (solo lectura, intento de escritura) o el documento rechaza la escritura: fuera de la sección del agente, sección bloqueada, agente pausado o excluido. |
429 | Más de 300 solicitudes en un minuto con este token: espera el número de segundos indicado en la cabecera Retry-After. |
409 | Al crearlo, desde tu espacio: ya hay un token activo con ese nombre. |
Enlaces
- La SKILL: SKILL.md, y sus referencias api.md, rules.md, markdown.md (en inglés).
- openapi.json: el esquema OpenAPI 3.1 de la API de los agentes, con el esquema de autenticación Bearer.
- SHA256SUMS: las huellas de los archivos de la SKILL; paginel.zip: la misma SKILL en un único archivo.
- Anthropic: Skills for enterprise y Agent Skills overview.
- OpenAI: Configuring actions in GPTs y GPT Action authentication.
- GitHub, para el formato de un token con prefijo y suma de control: Behind GitHub’s new authentication token formats.
Para ir más lejos
- Cómo funciona Paginel La aplicación, el servidor y cómo viajan tus cambios, sin jerga.
- Primeros pasos Crear una cuenta, abrir un archivo Word o Markdown, encontrar tus documentos.
- Invitar y compartir Invitar con un enlace o un código, elegir cuánto dura, quitar un acceso.
- Conectar Claude o ChatGPT En tres pasos: Claude o ChatGPT en tus documentos, y cómo quitarle el acceso.
- Escribir en Markdown La vista Markdown, la sintaxis útil, pegar Markdown, los agentes.
- Tomar notas en la vista Web Una página limpia sin hoja, donde el Markdown que escribes se formatea solo.
- Dar formato en la vista Edición Estilos, fuente y tamaño, imágenes, comentarios y el archivo de Word.
- Exportar a PDF La vista PDF, la descarga, PDF/A para archivar.
- Gestión de datos Dónde están tus documentos, quién puede leerlos, cómo recuperarlos y borrarlos.
- El conector de Paginel (MCP) El conector en detalle: Claude, ChatGPT, Claude Code, la autorización, el modo agente.
- Extensión para VS Code Tus archivos Markdown y Word en VS Code, el PDF, un archivo Markdown sincronizado para tus agentes.
- A local model (Ollama) An Ollama model reads and adds to a document on your computer; everything stays on the computer.
- Ayuda Las preguntas que más nos hacen.