Skip to content
agent-cms
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.

Updated Nov 21, 2026by docs seedVersion 1
On this page

note

From 0.14.0. Everything here is off until you set it. See Upgrade to 0.14.

Request limits#

ts
createCms({
  rateLimit: { perMinute: 600, anonymousPerMinute: 120 },
});
WhoCounted byLimit
An API keyThe keyIts own rateLimit, else perMinute
No key and no sessionThe caller's addressanonymousPerMinute
A signed-in personNot countedNone

Over the limit the answer is 429 with Retry-After in seconds:

json
{ "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:

ts
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:

ts
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, 0 to 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#

ts
createCms({
  retention: { auditDays: 365, hitsDays: 400, revokedKeysDays: 90, deliveriesDays: 14 },
});
OptionWhat goes
auditDaysAudit log entries older than this
hitsDaysRead counts older than this (the dashboard reads 30 days at most)
revokedKeysDaysKeys revoked longer ago than this
deliveriesDaysWebhook 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
json
{ "dryRun": true, "items": [{ "what": "audit", "days": 365, "before": "2025-11-21T00:00:00.000Z", "rows": 1204 }] }

Events as they happen#

ts
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 resync listing 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#

ts
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)],
  },
});
HookWhenCan it stop the action
beforeValidateBefore the input is checked. Return fields to change themYes, by throwing
beforeChange, beforePublish, beforeDeleteBefore the save, publish or delete (0.12)Yes
afterChange, afterPublish, afterDeleteAfter it happenedNo. Errors go to onError
afterReadBefore one document leaves get (not lists or search)Yes, by throwing

afterPublish also runs for a scheduled publish and for a release.