Guides / Limits, key rotation, retention and events
Guides / operations
Limits, key rotation, retention and events
Requests per minute for keys and strangers, addresses a key may be used from, a new secret without downtime, how long logs are kept, and a live stream of what happens.
On this page
note
From 0.14.0. Everything here is off until you set it. See Upgrade to 0.14.
Request limits#
createCms({
rateLimit: { perMinute: 600, anonymousPerMinute: 120 },
});| Who | Counted by | Limit |
|---|---|---|
| An API key | The key | Its own rateLimit, else perMinute |
| No key and no session | The caller's address | anonymousPerMinute |
| A signed-in person | Not counted | None |
Over the limit the answer is 429 with Retry-After in seconds:
{ "error": "rate_limited", "message": "Too many requests. Try again in 42 seconds", "params": { "retryAfter": 42, "limit": 60 } }A minute is a fixed window: the count starts over when the clock minute ends. Counts live in the server process. With several servers, or on a serverless host, give a store they share; it needs one method:
rateLimit: {
perMinute: 600,
store: {
hit: async (bucket, ttlMs) => {
const n = await redis.incr(bucket);
if (n === 1) await redis.pexpire(bucket, ttlMs);
return n;
},
},
}The address comes from X-Forwarded-For (first entry), then X-Real-IP. A server that is not behind a proxy setting those should say where it is: createCmsHandler({ clientIp: (req) => … }).
A key's own limit and addresses#
On the keys screen, or:
await cms.createKey(admin, { name: "deploy", scopes: ["read", "write"], rateLimit: 60, allowedIps: ["203.0.113.0/24", "2001:db8::/32"] });From any other address the key answers 403 forbidden_ip. Up to 50 addresses or ranges, IPv4 and IPv6.
Rotating a key#
"Rotate" on the keys screen, or POST /keys/:id/rotate with { "graceMinutes": 60 }:
- A new secret is made with the same name, scopes, collections, expiry and limits. It is shown once.
- The old secret keeps working for the grace time (60 minutes by default, up to 7 days,
0to stop it now), so callers can switch without a break. - The list shows the old key with "Works until …", then as "Replaced".
DELETE /keys/:id?reason=leaked keeps a note with a revoked key.
Retention#
createCms({
retention: { auditDays: 365, hitsDays: 400, revokedKeysDays: 90, deliveriesDays: 14 },
});| Option | What goes |
|---|---|
auditDays | Audit log entries older than this |
hitsDays | Read counts older than this (the dashboard reads 30 days at most) |
revokedKeysDays | Keys revoked longer ago than this |
deliveriesDays | Webhook deliveries (they are kept 30 days without it) |
The cron call applies the rules at most once a day and writes one audit entry when it deleted something. Documents, their versions (versions.max on a collection) and the trash (trash.days) are not part of it.
Look before it runs:
npx @mainsoft/agent-cms retention --dry-run # needs an admin key{ "dryRun": true, "items": [{ "what": "audit", "days": 365, "before": "2025-11-21T00:00:00.000Z", "rows": 1204 }] }Events as they happen#
const es = new EventSource("/api/cms/_events?collections=posts");
es.addEventListener("doc.published", (e) => refresh(JSON.parse(e.data).slug));
es.addEventListener("resync", (e) => JSON.parse(e.data).documents.forEach((d) => refresh(d.slug)));GET /_events is a Server-Sent Events stream of the same events webhooks carry (doc.created, doc.updated, doc.published, …).
- Someone who may write in a collection hears everything about its documents.
- A reader, such as a stranger on a public collection, hears only what changes the public copy: published, unpublished, archived, deleted, restored.
- Events without a collection (files, releases) go to admins.
- Every message has an id, a time. When the browser reconnects it sends the id back, and the first message is one
resynclisting the documents saved since (up to 200).?since=<ISO time>does the same by hand.
warning
The stream is fed by the server process that answers it. With several servers, a change made through another one arrives with the next resync, not live. Hosts that cut long responses (serverless) end the stream after their time limit; EventSource reconnects by itself.
In code: const stop = cms.subscribe((event) => …).
More hooks#
defineCollection({
slug: "posts",
hooks: {
beforeValidate: [({ input, prev }) => (!prev && !input.slug && input.title ? { slug: slugify(input.title) } : undefined)],
afterPublish: [(doc) => revalidatePath(`/blog/${doc.slug}`)],
afterDelete: [(doc) => searchIndex.remove(doc.id)],
afterRead: [(doc, { actor }) => (actor.kind === "anonymous" ? { ...doc, fields: { ...doc.fields, internalNote: undefined } } : undefined)],
},
});| Hook | When | Can it stop the action |
|---|---|---|
beforeValidate | Before the input is checked. Return fields to change them | Yes, by throwing |
beforeChange, beforePublish, beforeDelete | Before the save, publish or delete (0.12) | Yes |
afterChange, afterPublish, afterDelete | After it happened | No. Errors go to onError |
afterRead | Before one document leaves get (not lists or search) | Yes, by throwing |
afterPublish also runs for a scheduled publish and for a release.