[revalidate]

The token that turns on POST /_gio/revalidate, the endpoint CMS webhooks and scripts use to purge cached pages by tag or path.

# preferred: keep the token out of gio.toml
export GIO_REVALIDATE_TOKEN=$(node -e "console.log(require('crypto').randomBytes(32).toString('base64url'))")

[revalidate]
token = "replace-with-at-least-32-random-bytes-of-secret"

Without a token the endpoint does not exist. Inside the app, revalidateTag and revalidatePath purge the cache with no token at all.

Reference

Behavior

The endpoint takes a JSON body with tags and/or paths (up to 64 each) and prefix (true purges every path and everything below it). Matching pages are dropped from memory and disk, so the next request renders fresh.

Errors

the revalidation token ([revalidate] token) is 5 bytes; at least 32 are required (or (GIO_REVALIDATE_TOKEN)) stops startup and fails --check-config.

Examples

Purge from a CMS webhook

curl -X POST https://example.com/_gio/revalidate \
  -H "Authorization: Bearer $GIO_REVALIDATE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "tags": ["post:42"], "paths": ["/blog"], "prefix": true }'

Good to know

• The endpoint is authenticated by its token, not by cookies, so [security.csrf] does not apply to it. Call it over HTTPS.
• Each instance has its own cache: with several instances, call every one of them, by its own address.
• Behind a reverse proxy, list it in [server] trusted_proxies: otherwise the failed-attempt limit counts every client as the proxy.
• With i18n on, a leading locale segment is dropped from a path, so the purge reaches every locale of the page.

Not configurable

• The 32-byte minimum. The endpoint is public, so the token is the only thing between it and a purge flood.
• The failed-attempt limit (10 per minute per client) and the 64 tags / 64 paths per request.

Related

• Caching: From outside
• [cache]
• tags
• Environment variables

Version history