Dans la documentation Jetons d’API
Développeurs et agents
Les jetons d’API
Un jeton d’API laisse un agent d’IA, un script ou un outil travailler sur vos documents sans connaître votre mot de passe, avec les seuls droits que vous lui donnez. Un jeton neuf n’ouvre rien ; vous le retirez quand vous voulez.
Ce qu’est un jeton d’API
Un jeton est une longue suite de caractères secrète, qui commence par pgn_. L’agent l’envoie avec chaque requête à l’API REST de Paginel (Authorization: Bearer pgn_…) : Paginel reconnaît alors le jeton, pas une personne. Il ne donne que ce qu’on lui a donné.
Chaque jeton porte le nom de son client (claude-code, chatgpt…). Dans le document, l’agent apparaît sous ce nom (agent:claude-code) : ce qu’il écrit est signé et daté dans l’historique, et se défait comme le reste. Vous pouvez le mettre en pause ou l’exclure du document, et révoquer son jeton à l’instant.
Un jeton ne peut pas créer d’autres jetons : seule une personne connectée le peut. Paginel n’appelle aucun modèle de lui-même : le jeton sert à l’agent que vous avez choisi, chez le fournisseur que vous avez choisi (voir Gestion des données).
Le créer
Il y a deux endroits.
- Depuis le document, en ligne sur Paginel : le panneau Agent (Insertion › Agent), puis Agent en ligne ; ou un clic droit sur un titre, Brancher un agent sur cette section…. Le dialogue propose d’abord le connecteur Paginel ; ouvrez Pour les développeurs : un jeton (script, API), puis Donner l’accès. Si un jeton actif, fait à la main, porte déjà le nom de l’agent, Paginel lui ajoute un droit sur ce document (ou sur la section choisie) ; sinon, il crée le jeton avec ce premier droit et le montre une seule fois. Ensuite, deux gestes : 1. mettre le jeton dans la variable
PAGINEL_TOKENde votre agent (« Copier le jeton ») ; 2. « Copier le texte pour l’agent ». Le texte copié ne contient jamais le jeton. - Depuis Agents et API, dans votre espace, partie repliée Pour les développeurs : « Nouveau jeton », puis, pour chaque jeton, « Ajouter un droit », « Renouveler » ou « Révoquer ».
Un seul jeton actif par nom et par compte : en créer un second du même nom est refusé, il faut renouveler le premier ou lui ajouter un droit ; le nom d’une application branchée est pris, lui aussi. Un nom tient en lettres, chiffres, tirets et tirets bas, 32 signes au plus. Paginel ne garde pas le jeton lui-même, seulement son empreinte : un jeton perdu ne se retrouve pas, on le renouvelle.
Les droits : ce que le jeton ouvre
Un jeton n’ouvre rien tant qu’on ne lui a pas donné un droit. Il ouvre ce que la réunion de ses droits non échus ouvre ; pour un même document, c’est le droit le plus fort qui compte.
| Un droit se compose de | Au choix |
|---|---|
| Une portée | Un document, un dossier (les documents qui y sont au moment de la requête), ou tous vos documents. Pour un document, on peut préciser une section. |
| Un niveau | Lecture : lire le document. Commentaire : lire et commenter. Modification : lire, commenter, écrire et renommer ; sur un dossier, aussi y créer des documents. |
| Une échéance | 7, 30, 90 ou 365 jours, ou aucune ; 30 jours par défaut depuis le document. Le jeton a aussi la sienne, choisie dans la même liste. |
Un droit de section est imposé par le cœur du document, pas seulement par le jeton : Paginel inscrit l’agent dans le document avec la section qui lui est confiée, et toute écriture ailleurs est refusée ; l’agent lit le reste. Si cette inscription échoue, aucun droit n’est créé.
Ce qu’un agent ne peut jamais faire
- Supprimer un document, ou le déplacer d’un dossier à l’autre.
- Créer, renouveler ou révoquer des jetons.
- Écrire là où aucune personne ne le lui a permis : un agent écrit dans les sections qu’on lui a confiées, ou dans tout le document dans la limite des droits de son responsable, quels que soient les droits de son jeton.
Retirer un accès
Retirer un droit coupe l’accès à ce document, ou à cette section, et à lui seul ; révoquer le jeton coupe tout, à l’instant. Dans le document, sous Pour les développeurs : un jeton (script, API), Accès de ce document liste les agents qui y ont accès (portée, droits, échéance, dernière utilisation), avec « Retirer » ; seule la personne à qui le document appartient voit cette liste.
Où mettre le jeton
Donnez le jeton à votre agent par des variables d’environnement, trois en tout :
PAGINEL_URL: l’adresse de la plateforme, par exemplehttps://paginel.com;PAGINEL_TOKEN: le jeton,pgn_…;PAGINEL_DOC: l’identifiant du document, la fin de son adresse…/d/<identifiant>.
Terminalexport PAGINEL_URL="https://paginel.com"export PAGINEL_TOKEN="pgn_…"export PAGINEL_DOC="identifiant-du-document" Jamais dans une adresse (les adresses sont gardées dans des journaux), dans un document, dans un commentaire, dans un dépôt de code ni dans une conversation partagée. La SKILL le dit aussi à l’agent : n’envoyer le jeton qu’à PAGINEL_URL, et ne jamais l’afficher, le journaliser ni l’écrire.
Un premier appel
Une fois les variables posées, voici comment demander à l’agent ses consignes (qui est son responsable, où il peut écrire), puis lire le document :
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" Les consignes donnent aussi les demandes à l’agent laissées dans le document (le panneau Agent, « Demandes à l’agent » : « Nouvelle demande… », ou Insertion › Demander à l’agent…), dans le champ requests : l’agent écrit dans le passage visé, puis marque la demande terminée. Toutes les routes sont décrites dans openapi.json et dans la SKILL (voir « Liens » plus bas).
Claude Code : installer la SKILL
Une SKILL est un dossier de fichiers qui apprend à l’agent ce qu’est Paginel, ses règles et toute l’API. La plateforme la sert, publique et sans jeton, à une adresse versionnée (/agent/v1/) ; elle suit l’API et s’enrichit quand Paginel gagne des fonctions. Installez-la, vérifiez les empreintes publiées avec elle, et réinstallez-la après une mise à jour :
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 partie « Pour les développeurs » de la page Agents et API affiche aussi cette installation, avec « Copier la commande ». Le texte copié depuis un document dit à l’agent d’utiliser la skill paginel et, si elle n’est pas installée, de lire /agent/v1/SKILL.md et de vérifier /agent/v1/SHA256SUMS. Voir aussi Anthropic, Agent Skills.
L’app Claude et ChatGPT : le connecteur
Dans l’app Claude (web, ordinateur, téléphone) et dans ChatGPT, le plus simple est le connecteur Paginel : vous l’autorisez une fois, pour ce que vous choisissez, sans copier de jeton. L’application branchée apparaît ensuite dans Agents et API, sous Applications branchées, avec « Ce qu’il voit » et « Couper l’accès ». Voir Brancher Claude ou ChatGPT.
Dans Claude Desktop, la SKILL reste possible : téléversez paginel.zip dans Personnaliser › Skills (le dossier paginel/ et ses quatre fichiers, sans aucun jeton). D’après la documentation d’Anthropic, l’accès au réseau d’une skill dépend des réglages de l’appli : complet, partiel ou nul, selon l’utilisateur ou l’administrateur (Anthropic, Skills overview) ; Paginel doit y être autorisé.
Une appli de bureau n’a pas forcément accès à vos variables d’environnement : il faudrait donner le jeton dans la conversation, où il resterait dans l’historique. Préférez le connecteur ; sinon, prenez un droit étroit et une échéance courte, et révoquez le jeton ensuite.
ChatGPT : un GPT avec des Actions
Sans le connecteur, l’autre chemin est un GPT personnalisé avec des Actions : importez openapi.json comme schéma, et mettez le jeton dans les réglages d’authentification de l’action (clé d’API, type Bearer), pas dans le schéma. Selon OpenAI, le secret d’une clé d’API y est chiffré, et le schéma est à part. Voir OpenAI, Configuring actions in GPTs et GPT Action authentication ; vérifiez-y ce que votre offre permet.
Pour vous seul. Selon OpenAI, l’accès propre à chaque personne passe par OAuth : c’est ce que fait le connecteur. Un jeton Paginel mis dans une Action est le vôtre : ne l’utilisez que dans un GPT privé, avec un droit étroit (un document ou une section, une échéance courte). Ces pages ne disent pas ce que voient les personnes qui utilisent un GPT partagé : par prudence, ne mettez pas ce jeton dans un GPT que d’autres utilisent.
Un script, ou un autre agent
Tout outil qui sait faire des requêtes HTTP peut appeler l’API avec le jeton, comme dans l’exemple plus haut. openapi.json décrit les routes ; la SKILL, écrite en anglais pour les agents, décrit en plus les règles de Paginel.
Bonnes pratiques
Les cinq premières sont les nôtres ; les deux suivantes reprennent ce que disent les éditeurs d’agents, avec leurs liens plus bas.
- Des droits étroits. Un document ou une section plutôt que tous vos documents ; « commentaire » plutôt que « modification » quand l’agent n’a pas à écrire. Si le jeton fuit, il n’ouvre que cela.
- Une courte durée. 30 jours par défaut depuis le document ; évitez « aucune échéance ».
- Un jeton par client : un pour Claude Code, un autre pour ChatGPT. On sait qui a fait quoi, et on coupe l’un sans toucher l’autre.
- Renouveler. « Renouveler » crée un nouveau jeton avec les mêmes droits ; l’ancien reste valable 10 minutes, le temps de changer la variable, puis il est révoqué.
- Surveiller et révoquer. La liste dit la dernière utilisation et la dernière adresse vue, tronquée (le réseau, jamais la machine entière). L’espace signale une « adresse inhabituelle » quand un jeton sert depuis un autre réseau que la fois d’avant ; Paginel n’envoie pas de courriel. Au moindre doute, révoquez.
- Aucun identifiant écrit dans une skill. Anthropic classe parmi les risques élevés les identifiants écrits dans une skill (ils finissent dans l’historique Git et dans la fenêtre de contexte) et demande des variables d’environnement ou des coffres sécurisés. La SKILL de Paginel ne contient aucun jeton ; un test le vérifie.
- Installer plutôt que lire à chaque fois. Anthropic met en garde contre une skill qui va chercher ses instructions à une adresse (elle peut être compromise si ce qu’elle charge change), conseille de la traiter comme un logiciel qu’on installe, de fixer les versions et de vérifier une empreinte. D’où la SKILL installée, à une adresse versionnée, avec ses
SHA256SUMS; la lire à l’adresse n’est qu’un secours. Elle n’a aucun script et n’envoie le jeton qu’àPAGINEL_URL.
Si un jeton a fuité
Publié dans un dépôt, copié dans une conversation, visible sur une capture : révoquez-le tout de suite, depuis Agents et API. La liste dit quand et d’où il a servi pour la dernière fois. Créez ensuite un autre jeton, avec des droits aussi étroits.
Référence
| Sujet | Ce que fait Paginel |
|---|---|
| Format | pgn_, puis 64 caractères hexadécimaux au hasard, puis 6 caractères de somme de contrôle (CRC32 en base 62, comme les jetons de GitHub). Une somme fausse est refusée sans interroger la base ; l’ancien format, sans somme, reste accepté. Le préfixe et la somme permettent à un outil d’analyse de secrets de reconnaître un jeton Paginel sans le soumettre à Paginel. |
| Limites | 20 jetons actifs par compte, 100 droits par jeton, 300 requêtes par minute et par jeton. |
404 « Document inconnu. » | Le jeton est inconnu, révoqué ou échu, ou n’a aucun droit non échu sur ce document. |
403 | Le niveau du jeton ne suffit pas (lecture seule, qui veut écrire), ou le document refuse l’écriture : hors de la section de l’agent, section verrouillée, agent en pause ou exclu. |
429 | Plus de 300 requêtes en une minute avec ce jeton : attendez le nombre de secondes de l’en-tête Retry-After. |
409 | À la création, depuis votre espace : un jeton actif porte déjà ce nom. |
Liens
- La SKILL : SKILL.md, et ses références api.md, rules.md, markdown.md (en anglais).
- openapi.json : le schéma OpenAPI 3.1 de l’API des agents, avec le schéma d’authentification Bearer.
- SHA256SUMS : les empreintes des fichiers de la SKILL ; paginel.zip : la même SKILL en une archive.
- Anthropic : Skills for enterprise et Agent Skills, vue d’ensemble.
- OpenAI : Configuring actions in GPTs et GPT Action authentication.
- GitHub, pour le format d’un jeton avec préfixe et somme de contrôle : Behind GitHub’s new authentication token formats.
Pour aller plus loin
- Comment marche Paginel L’application, le serveur, et comment vos modifications voyagent, sans jargon.
- Démarrer Créer un compte, ouvrir un fichier Word ou Markdown, retrouver ses documents.
- Inviter et partager Inviter par un lien ou un code, choisir sa durée, retirer un accès.
- Brancher Claude ou ChatGPT En trois gestes : Claude ou ChatGPT dans vos documents, et comment couper son accès.
- Écrire en Markdown La vue Markdown, la syntaxe utile, coller du Markdown, les agents.
- Prendre des notes en vue Web Une page épurée, sans feuille, où le Markdown tapé se met en forme.
- Mettre en forme en vue Édition Styles, police et taille, images, commentaires, et le fichier Word.
- Exporter en PDF La vue PDF, le téléchargement, le PDF/A pour l’archivage.
- Gestion des données Où sont vos documents, qui peut les lire, comment les reprendre et les effacer.
- Le connecteur Paginel (MCP) Le connecteur en détail : Claude, ChatGPT, Claude Code, l’autorisation, le mode agent.
- Extension VS Code Vos Markdown et vos Word dans VS Code, le PDF, un Markdown synchronisé pour vos agents.
- Un modèle local (Ollama) Un modèle d’Ollama lit et complète un document de votre ordinateur ; tout reste sur l’ordinateur.
- Aide Les questions qu’on nous pose le plus.