In the documentation API tokens
Developers and agents
API tokens
An API token lets an AI agent, a script or a tool work on your documents without knowing your password, with only the rights you give it. A new token opens nothing; you can take it back whenever you want.
What an API token is
A token is a long secret string that starts with pgn_. The agent sends it with every request to Paginel’s REST API (Authorization: Bearer pgn_…): Paginel then recognises the token, not a person. It gives only what it was given.
Each token carries the name of its client (claude-code, chatgpt…). In the document, the agent appears under that name (agent:claude-code): what it writes is signed and dated in the history, and can be undone like anything else. You can pause it or exclude it from the document, and revoke its token instantly.
A token cannot create other tokens: only a signed-in person can. Paginel calls no model on its own: the token serves the agent you chose, at the provider you chose (see Data management).
Creating one
There are two places.
- From the document, online on Paginel: the Agent panel (Insert › Agent), then Online agent; or right-click a heading, Connect an agent to this section…. The dialog offers the Paginel connector first; open For developers: a token (script, API), then Give access. If an active token, made by hand, already bears the agent’s name, Paginel adds a right to it for this document (or the chosen section); otherwise it creates the token with that first right and shows it only once. Then two steps: 1. put the token in your agent’s
PAGINEL_TOKENvariable (“Copy token”); 2. “Copy the text for the agent”. The copied text never contains the token. - From Agents and API, in your space, folded part For developers: “New token”, then, for each token, “Add a right”, “Renew” or “Revoke”.
One active token per name and per account: creating a second one with the same name is refused; renew the first or add a right to it. A connected app’s name is taken too. A name is made of letters, digits, hyphens and underscores, 32 characters at most. Paginel does not keep the token itself, only its fingerprint: a lost token cannot be recovered, you renew it.
Rights: what the token opens
A token opens nothing until it has been given a right. It opens what the union of its unexpired rights opens; for a given document, the strongest right counts.
| A right is made of | Your choice |
|---|---|
| A scope | One document, one folder (the documents in it at the time of the request), or all your documents. For a document, you can narrow it to one section. |
| A level | Read: read the document. Comment: read and comment. Edit: read, comment, write and rename; on a folder, also create documents in it. |
| An expiry | 7, 30, 90 or 365 days, or none; 30 days by default from the document. The token has its own too, chosen from the same list. |
A section right is enforced by the document’s core, not only by the token: Paginel registers the agent in the document with the section it is given, and any write elsewhere is refused; the agent reads the rest. If that registration fails, no right is created.
What an agent can never do
- Delete a document, or move it from one folder to another.
- Create, renew or revoke tokens.
- Write where no person has allowed it: an agent writes in the sections it was entrusted with, or in the whole document within the limits of its owner’s rights, whatever its token’s rights are.
Taking access back
Removing a right cuts access to that document, or that section, and only that; revoking the token cuts everything, instantly. In the document, under For developers: a token (script, API), Access to this document lists the agents that have access (scope, rights, expiry, last use), with “Remove”; only the person who owns the document sees that list.
Where to put the token
Give the token to your agent through environment variables, three in all:
PAGINEL_URL: the platform’s address, for examplehttps://paginel.com;PAGINEL_TOKEN: the token,pgn_…;PAGINEL_DOC: the document’s identifier, the end of its address…/d/<identifier>.
Terminalexport PAGINEL_URL="https://paginel.com"export PAGINEL_TOKEN="pgn_…"export PAGINEL_DOC="document-identifier" Never in an address (addresses are kept in logs), in a document, in a comment, in a code repository or in a shared conversation. The SKILL tells the agent the same: send the token only to PAGINEL_URL, and never display it, log it or write it down.
A first call
Once the variables are set, here is how to ask for the agent’s instructions (who is responsible for it, where it may write), then read the 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" The instructions also give the agent requests left in the document (the Agent panel, “Agent requests”: “New request…”, or Insert › Ask the agent…), in the requests field: the agent writes in the passage concerned, then marks the request done. Every route is described in openapi.json and in the SKILL (see “Links” below).
Claude Code: installing the SKILL
A SKILL is a folder of files that teaches the agent what Paginel is, its rules and the whole API. The platform serves it, public and without a token, at a versioned address (/agent/v1/); it follows the API and grows when Paginel gains features. Install it, check the fingerprints published with it, and reinstall it after an update:
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 The “For developers” part of the Agents and API page also shows this installation, with “Copy the command”. The text copied from a document tells the agent to use the paginel skill and, if it is not installed, to read /agent/v1/SKILL.md and check /agent/v1/SHA256SUMS. See also Anthropic, Agent Skills.
The Claude app and ChatGPT: the connector
In the Claude app (web, desktop, phone) and in ChatGPT, the simplest way is the Paginel connector: you allow it once, for what you choose, without copying a token. The connected app then shows in Agents and API, under Connected apps, with “What it sees” and “Remove access”. See Connect Claude or ChatGPT.
In Claude Desktop, the SKILL is still possible: upload paginel.zip in Customize › Skills (the paginel/ folder and its four files, with no token in it). According to Anthropic’s documentation, a skill’s network access depends on the app’s settings: full, partial or none, depending on the user or the administrator (Anthropic, Skills overview); Paginel must be allowed there.
A desktop app does not necessarily have access to your environment variables: you would have to give the token in the conversation, where it would stay in the history. Prefer the connector; otherwise take a narrow right and a short expiry, and revoke the token afterwards.
ChatGPT: a GPT with Actions
Without the connector, the other way is a custom GPT with Actions: import openapi.json as the schema, and put the token in the action’s authentication settings (API key, Bearer type), not in the schema. According to OpenAI, an API key’s secret is encrypted there, and the schema is kept apart. See OpenAI, Configuring actions in GPTs and GPT Action authentication; check there what your plan allows.
For yourself only. According to OpenAI, access specific to each person goes through OAuth: that is what the connector does. A Paginel token put in an Action is yours: use it only in a private GPT, with a narrow right (one document or one section, a short expiry). Those pages do not say what the people who use a shared GPT can see: as a precaution, do not put this token in a GPT that others use.
A script, or another agent
Any tool that can make HTTP requests can call the API with the token, as in the example above. openapi.json describes the routes; the SKILL, written in English for agents, also describes Paginel’s rules.
Good practice
The first five are ours; the next two repeat what the agent vendors say, with their links below.
- Narrow rights. One document or one section rather than all your documents; “comment” rather than “edit” when the agent has no need to write. If the token leaks, it opens only that.
- A short life. 30 days by default from the document; avoid “no expiry”.
- One token per client: one for Claude Code, another for ChatGPT. You know who did what, and you cut one without touching the other.
- Renew. “Renew” creates a new token with the same rights; the old one stays valid for 10 minutes, long enough to change the variable, then it is revoked.
- Watch and revoke. The list gives the last use and the last address seen, truncated (the network, never the whole machine). Your space flags an “unusual address” when a token is used from a different network than the time before; Paginel sends no email. At the slightest doubt, revoke.
- No credentials written in a skill. Anthropic ranks credentials written in a skill as a high risk (they end up in the Git history and in the context window) and asks for environment variables or secure vaults. Paginel’s SKILL contains no token; a test checks it.
- Install rather than read every time. Anthropic warns against a skill that fetches its instructions from an address (it can be compromised if what it loads changes), advises treating it like software you install, pinning versions and checking a fingerprint. Hence the SKILL installed, at a versioned address, with its
SHA256SUMS; reading it at the address is only a fallback. It has no script and sends the token only toPAGINEL_URL.
If a token has leaked
Published in a repository, pasted in a conversation, visible in a screenshot: revoke it right away, from Agents and API. The list says when and from where it was last used. Then create another token, with rights just as narrow.
Reference
| Subject | What Paginel does |
|---|---|
| Format | pgn_, then 64 random hexadecimal characters, then 6 checksum characters (CRC32 in base 62, like GitHub’s tokens). A wrong checksum is refused without querying the database; the old format, without a checksum, is still accepted. The prefix and the checksum let a secret-scanning tool recognise a Paginel token without submitting it to Paginel. |
| Limits | 20 active tokens per account, 100 rights per token, 300 requests per minute per token. |
404 “Document inconnu.” | The token is unknown, revoked or expired, or has no unexpired right on that document. |
403 | The token’s level is not enough (read-only, wanting to write), or the document refuses the write: outside the agent’s section, locked section, agent paused or excluded. |
429 | More than 300 requests in a minute with this token: wait the number of seconds in the Retry-After header. |
409 | On creation, from your space: an active token already has that name. |
Links
- The SKILL: SKILL.md, and its references api.md, rules.md, markdown.md.
- openapi.json: the OpenAPI 3.1 schema of the agents’ API, with the Bearer authentication scheme.
- SHA256SUMS: the fingerprints of the SKILL’s files; paginel.zip: the same SKILL as one archive.
- Anthropic: Skills for enterprise and Agent Skills overview.
- OpenAI: Configuring actions in GPTs and GPT Action authentication.
- GitHub, for the format of a token with a prefix and a checksum: Behind GitHub’s new authentication token formats.
Going further
- How Paginel works The app, the server, and how your changes travel, without jargon.
- Get started Create an account, open a Word or Markdown file, find your documents.
- Invite and share Invite with a link or a code, choose how long it lasts, remove access.
- Connect Claude or ChatGPT In three steps: Claude or ChatGPT in your documents, and how to remove its access.
- Write in Markdown The Markdown view, the useful syntax, pasting Markdown, agents.
- Take notes in the Web view A clean page without a sheet, where typed Markdown formats itself.
- Format in the Edit view Styles, font and size, images, comments, and the Word file.
- Export to PDF The PDF view, downloading, PDF/A for archiving.
- Data management Where your documents are, who can read them, how to take them back and erase them.
- The Paginel connector (MCP) The connector in detail: Claude, ChatGPT, Claude Code, the authorization, the agent mode.
- VS Code extension Your Markdown and Word files in VS Code, the PDF, a synced Markdown file for your agents.
- A local model (Ollama) An Ollama model reads and adds to a document on your computer; everything stays on the computer.
- Help The questions we are asked most.