Sign in Create an account Create my account My documents

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_TOKEN variable (“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 ofYour 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 example https://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 to PAGINEL_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

SubjectWhat 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

Going further