A site needs a handful of variables to find the platform and prove who it is. kwisple link writes them to .env for local development; in CI and production you set the same names yourself (or let a managed host do it). This page lists every variable, then explains tokens.
The variables
Written by kwisple link
| Variable | Example | Meaning | Where it comes from |
|---|---|---|---|
KWISPLE_URL | https://api.kwisple.com (local: http://localhost:4101) | Base URL of the platform's delivery API. The SDK calls <KWISPLE_URL>/api/v1/*. | The platform's web URL. |
KWISPLE_TOKEN | kwi_… | The site API token the SDK sends as Authorization: Bearer. | A token with the right scopes (below). kwisple link creates one with read + preview + schema. |
KWISPLE_WEBHOOK_SECRET | hex string | Verifies the publish webhook's x-kwisple-signature (HMAC-SHA256 of the raw body). Also the key app sessions and staging tickets are derived from. | Website → Instellingen → Ontwikkeling → Webhook-geheim. Generated when the site is first linked or saved with a webhook URL; Vernieuwen replaces it. |
KWISPLE_DASHBOARD_ORIGIN | https://app.kwisple.com (local: http://localhost:4100) | The dashboard that frames the site: the allowed postMessage origin for <LivePreview> and connectApp, the base of the apps API for appPlatform, and the origin to allow in frame-ancestors. | The dashboard's origin. White-label agencies have their own. |
KWISPLE_ASSET_ORIGIN | https://assets.kwisple.com (local: http://localhost:9100) | Where uploaded assets are served from. Next: images.remotePatterns in next.config.ts; Astro: image.remotePatterns through the integration. | The platform's storage origin. |
KWISPLE_SITE | site id | The linked site's id. kwisple ci-token uses it to know which site to make a token for. Not read by the SDK at runtime. | Written by kwisple link; also set by a managed hosting connection. |
Astro's .env keeps KWISPLE_SITE too; it is harmless there.
Set by the CLI or by you
| Variable | Set by | Meaning |
|---|---|---|
KWISPLE_SCHEMA | kwisple dev (for the dev server it starts) | dev: the SDK reads with the site's development model and sends x-kwisple-schema: dev. Anything else or unset: the live model. createClient({ schemaEnv }) overrides it. Never set it in production. |
KWISPLE_ENV | You, on the staging deployment (and at build time there) | staging: the SDK's isStaging() is true. The staging gate runs, robots disallows everything, the sitemap is empty, statistics, 404 reports and AI-agent reports are off. See Staging. |
KWISPLE_REDIRECTS_IN_PROXY | You (Next starter only) | 1: proxy.ts checks dashboard redirects before rendering (one API call per request). Default 0: redirects are followed on a 404 only. |
KWISPLE_DASHBOARD_URL | You (CLI only) | Which dashboard the CLI talks to, when --dashboard is not given. Falls back to the project's KWISPLE_DASHBOARD_ORIGIN, then your last login, then https://app.kwisple.com. |
KWISPLE_CONFIG_DIR | You (CLI only) | Where kwisple login stores credentials.json (default ~/.config/kwisple, or %APPDATA%\kwisple on Windows). |
KWISPLE_DEPLOY_HOOK | You, as a GitHub Actions secret | Optional: the starter's workflow POSTs it after a successful kwisple push on main, for a strict "schema first, then build" order. |
KWISPLE_TEMPLATES_DIR | You (create-kwisple-site only) | A folder with astro/ and next/ starters to copy from instead of the packaged ones. |
NEXT_OUTPUT | The RANSON.N Dockerfile | standalone: next.config.ts sets output: "standalone" for the container image. Site-specific; copy the pattern if you build a Docker image. |
Platform-side variables you may hear about
These are set on the platform, not in your site. They decide which options the dashboard offers:
| Variable (platform) | Effect you see |
|---|---|
CLOUDFLARE_ACCOUNT_ID, CLOUDFLARE_API_TOKEN | The Cloudflare host appears under Koppel een repository. |
SITE_SERVER_ADDRESSES | The choice Op de server van het platform appears under Waar draait de website? (Domein), with those A/AAAA addresses. |
HOSTING_FAKE | 1 enables the Testhost (lokaal) provider outside development. |
OUTBOUND_ALLOW_PRIVATE | In production the platform only POSTs webhooks and deploy hooks to https public addresses; 1 allows private targets (development allows them by default). Matters when your webhook URL points at a private host. |
Build time versus runtime
| Variable | Next.js | Astro |
|---|---|---|
KWISPLE_URL, KWISPLE_TOKEN | Both. next build prerenders the layout, the 404 page, sitemap and robots from the live API, so the build needs a working token; at runtime every request reads with it. | Both for on-demand sites (astro build prerenders nothing content-related by default, but the integration warns when they are missing; the server reads them at runtime through astro:env). A static build reads everything at build time. |
KWISPLE_WEBHOOK_SECRET | Runtime (/api/revalidate, app sessions, staging gate). | Runtime (same). Not needed in a static build. |
KWISPLE_DASHBOARD_ORIGIN | Runtime for <LivePreview>, appPlatform; build time when next.config.ts puts it into a frame-ancestors header, as RANSON.N does. | Runtime (kwispleEnv.dashboardOrigin). |
KWISPLE_ASSET_ORIGIN | Build time: next.config.ts turns it into images.remotePatterns. The Dockerfile passes it as a build arg for that reason. | Config time: the integration reads it when Astro loads the config (astro dev, astro build, astro preview). |
KWISPLE_ENV | Both: robots and sitemap are generated at build time on a static-ish build, and the gate runs at runtime. | Both, for the same reasons. |
KWISPLE_SCHEMA | Runtime of the dev server only. | Same. |
How the files are read:
- Next loads
.envand.env.localitself (.env.localwins;kwisple linkwarns when it shadows a key). - Astro loads
.env,.env.<mode>,.env.localand.env.<mode>.localforastro devandastro build;astro previewgets them from the integration; the productionstartscript usesnode --env-file-if-exists=.env. In production set the variables in the host's environment instead of shipping a file. - The CLI (
kwisple push,status,seed,export,ci-token) loads.env.localthen.envfrom the current folder, or reads the process environment (CI).
Per environment
| Environment | How the variables get there | Token scopes |
|---|---|---|
| Local | kwisple link writes .env (mode 0600, kept out of git). | read + preview + schema (one token per machine and project; re-linking replaces it). |
| CI (GitHub Actions) | npx kwisple ci-token --gh stores KWISPLE_URL and KWISPLE_TOKEN as repository secrets, or paste the values from kwisple ci-token / Hosting & deploys → Geavanceerd → CI-token maken. Only the CLI runs there; no webhook secret or dashboard origin needed. | read + schema (the token is named CI (GitHub Actions)). |
| Production, managed host (Cloudflare) | The platform sets all six variables for production and previews when you connect the repository, with a fresh token named Hosting · Cloudflare. Ontkoppelen revokes it. | read + preview. |
| Production, own host (deploy hook) | Set them yourself in the host's environment: the same names as .env. Variabelen van de site in the dashboard lists the names. | A token you create under API-tokens with read + preview, never schema. |
| Production, the platform's server (Docker) | A .env.production file next to the repository checkout on the server, mounted as a BuildKit secret at build time and used as env_file at runtime (RANSON.N). | read + preview. |
| Staging | The staging site's own values (kwisple link → pick the (staging) entry, or copy them from the staging's Instellingen → Ontwikkeling), plus KWISPLE_ENV=staging. On the platform's server: .env.staging. | read + preview (+ schema only if the staging branch's CI pushes its own model). |
Never commit .env. The starters ignore it; kwisple link adds it to .gitignore when missing; .dockerignore in RANSON.N excludes .env* except .env.example.
Tokens
Site API tokens and scopes
A site API token starts with kwi_ and belongs to one site. It is stored hashed; you see it once. Scopes:
| Scope | Dashboard label | Allows | Who needs it |
|---|---|---|---|
read | Lezen (gepubliceerd) | GET /site, /entries, /entry (live), /tree, /globals, /brand, /consent, /schema, /redirects/match; POST /forms, /not-found, /agent. | Every deployment. |
preview | Preview (concepten) | GET /preview/verify and draft content with x-kwisple-preview. | Every deployment that serves live preview (production and staging), and your local machine. Not CI. |
schema | Contentmodel pushen | POST /schema (kwisple push, kwisple dev), and the kit endpoints behind kwisple export. | Your local machine and CI. Never production. |
Which scope for which task:
- Rendering the site:
read. - Live preview for editors:
read + preview. kwisple dev/kwisple push/kwisple status:read + schema.- A production deployment:
read + preview(editors preview on production too). Leaveschemaout, so a leaked production token cannot change the model.
A request with a token that lacks the scope fails with 401/403 and { error: { code, message } }; the SDK throws a KwispleError with status and code.
Creating a token in the dashboard
Website → Instellingen → Ontwikkeling (the Ontwikkeling tab; agency team only), card API-tokens:
- Naam: something that tells you where it lives (the placeholder suggests
Productie / Lokaal Robbe / CI). - Rechten: tick Lezen (gepubliceerd), Preview (concepten) and/or Contentmodel pushen.
- Token aanmaken (create token). The dashboard shows "Token aangemaakt. Kopieer het nu: je ziet het maar één keer."
The list shows every token with its rights, Laatst gebruikt (last used) or Nooit gebruikt (never used), and Intrekken (revoke). Revoked tokens stay listed as Ingetrokken.
Tokens made for you
| Name in the list | Made by | Scopes | Replaced or revoked when |
|---|---|---|---|
kwisple link · <machine> · <project> | kwisple link | read + preview + schema | You link the same project from the same machine again (replaced). |
| CI (GitHub Actions) | kwisple ci-token or CI-token maken | read + schema | You create a new CI token (the same person's earlier one is replaced). |
| Hosting · Cloudflare | Connecting a Cloudflare repository | read + preview | Ontkoppelen (revoked). |
Rotating
- Create the new token (dashboard or CLI).
- Put it in the environment of every deployment that used the old one (host settings,
.env.production, GitHub secrets) and redeploy or restart. - Intrekken the old one. Reads with it fail immediately.
For the webhook secret: Vernieuwen under Webhook-geheim makes a new one at once ("Nieuw geheim aangemaakt. Zet het ook in de site."). Until the site runs with the new value, /api/revalidate answers 401 to the platform and the dashboard reports the failed webhook after publishing; app sessions and staging tickets signed with the old secret stop verifying too. Rotate it in a quiet moment and redeploy right after.
The CLI token
kwisple login stores a personal token (kwicli_…) in ~/.config/kwisple/credentials.json (mode 0600). It is never printed and only sent to the dashboard's /api/cli/* endpoints. It works with your rights, so it can link sites, push models and create site tokens for the clients where you have the developer right, never more. Revoke it with kwisple logout or under Instellingen → Koppelingen → Terminal in the dashboard. After a revocation the CLI says Je sleutel is ingetrokken and you log in again.
Never commit secrets
.envis in.gitignore; keep it there.kwisple linkmakes the file owner-only.- The start prompt generated by the dashboard contains no secrets, so it is safe to paste into a coding assistant.
- Deploy hooks and status URLs you paste in the dashboard are encrypted at rest and never shown again.
- If a token leaks: Intrekken first, then create a new one. Content is never at risk from a
read + previewtoken (it can only read, including drafts), but aschematoken can change the content model, so production never gets one.