API tokens and security

An API token authenticates a machine against one project: the loader during a build, the CLI on your machine. Every token belongs to a single project and carries a scope that bounds what it can do. The rule: always the smallest scope that does the job.

The three scopes

Scope	Secret prefix	Used for
read_published	cmt_pub_	Reading published content: the loader at build time, menestrel pull.
read_draft	cmt_drf_	The upcoming draft preview. Today it reads the same content as read_published.
admin	cmt_adm_	The developer machine: sync, import, export, schema reads, content writes through the API.

read_published covers everything a public site needs: fetching the latest published snapshot and its files. It is the build scope, and a public deployment never needs more. In production, the best token is no token at all: with MENESTREL_CONTENT_URL, the build no longer depends on the API. See Environment variables.

read_draft is reserved for previews: a review deployment that will also show drafts. That preview is not open yet: for now, this scope reads exactly the same published content as read_published. Never put it on the public site: a preview that exposes drafts publishes what was not ready.

admin is the developer-side CLI scope. menestrel sync, import and export check it and refuse any other scope (exit code 5); menestrel init warns when the provided token is not admin. It is also the scope required to read the schema and write content through the API.

Note

The prefix states the scope, so a .env file reads without ambiguity. The full secret is shown exactly once, at creation; the server only keeps a SHA-256 digest. A lost secret cannot be displayed again: revoke the token and create a new one.

The life of a token

• Creation: project settings, “API tokens” tab. Restricted to organization owners and admins. Expiry is optional: 90 days, 1 year, a date of your choice, or never.
• Monitoring: the list shows each token’s last use. A token “never used” for months is a candidate for revocation.
• Revocation: immediate. Anything using the token stops on the next request. A revoked or expired token gets the same 401 response, with no explanation: a stolen secret teaches nothing to whoever probes it.
• Audit: creation and revocation are logged, with author and date.

Good practices

• One token per use. “Vercel build”, “GitHub CI”, “Lea’s laptop”: three tokens, not one shared secret. Revoking one does not kill the others, and the label tells you what breaks if you revoke.
• Never in the repo. A token lives in an environment variable. menestrel init writes it to .env and adds .env to .gitignore; on Vercel, Netlify or in CI, use the project’s environment variables.
• Rotation without downtime. Create the new token, switch the environments over, revoke the old one. Two valid tokens coexist just fine.
• If a token leaks, revoke first. Revocation is immediate and has no effect on other tokens: start there, then investigate how the secret got out.

Your data: where, and under which rules

Hosted in France. The database, media and snapshots are hosted at Scaleway, Paris region. Public delivery goes through a European CDN (Bunny).

GDPR. For content and editor accounts, Menestrel acts as a processor: DPA signable online, public list of sub-processors (Scaleway, Bunny, Stripe for payments, Scaleway TEM or Brevo for emails), any addition announced 30 days in advance. No third-party trackers in the admin.

Retention. After cancellation, content is kept for 30 days, with an export offered before deletion. Backups are kept 30 days, logs 12 months.

Full export, any time. npx menestrel export gets everything out: content/ as Markdown, data/ as JSON, media/ with the originals. No proprietary format, no notice period, no support ticket: the day you leave, you leave with everything. See the CLI reference.