Hosted diagrams and plans

Audit log

An organisation's audit log says who changed what in the organisation, and when. The owner and the admins read it in the portal, and on Enterprise they export it, or have their SIEM poll it with a key that can do nothing else.

TL;DR

Question	Answer
Which plan?	Pro keeps 30 days of events and shows them in the portal. Enterprise keeps 365 days, or the days the contract sets, and adds the export. The Free plan records nothing.
Who can read it?	The owner and the admins, on the organisation's Audit log tab. A member and a reader cannot. On Enterprise, an organisation API key with the `audit:read` scope can too.
What is recorded?	Members, invitations and roles, ownership, API keys, diagrams, folder rules, the brand, icons, avatar and style rules, "Keep diagrams editable", drift reports from CI, single sign-on (its settings, its domains, every sign-in through your provider, failed ones, people added on first sign-in, and the owner's emailed-code sign-ins while it is required), and changes Plotwork support made, with the reason given.
What is never in it?	A diagram's source, a key's value, a token, a color, or a full IP address.
How does a SIEM get it?	It polls `GET /orgs/{org}/audit/export` with a key that has only `audit:read`, and sends the `Plotwork-Next-Cursor` header back as `after` each time.
Is there a push?	Yes, on Enterprise: each event can be sent as it happens to Datadog, Dynatrace, Splunk, Microsoft Sentinel or a signed webhook. See Send audit events and drift to your tools. Polling the export still works, and is the record to reconcile against.

1. Read the log

Open the organisation in the portal and choose the Audit log tab. The newest events come first, a page at a time, with a button for older ones.

Column	What it shows
When	How long ago, with the exact time on hover
Who	A member's email address, a key's name tagged API key, CI tagged CI, or Plotwork support
What	What happened, with facts such as the role given or the setting chosen
On	What it was done to: a member, an invited address, a key, a diagram, an icon or a folder
From	The network the request came from: an IPv4 /24 or an IPv6 /48, never the full address

Three filters narrow the list, and each reaches every event the plan keeps:

Filter	Narrows to
What	One group of actions, such as Members or API keys
Who	One email address or key name, as the log shows it. Choose a suggestion or press Enter.
When	The last 24 hours, 7 days, or 30 days

2. Export it (Enterprise)

The tab has two downloads, CSV and JSON Lines, with the filters you chose. One file holds up to 1,000 events, oldest first. Downloading is itself recorded.

The same export is an API route:

1curl -s "https://api.plotwork.dev/orgs/acme-platform/audit/export?format=jsonl" \2  -H "X-API-Key: $PLOTWORK_AUDIT_KEY" -D headers.txt -o events.jsonl

Parameter or header	Meaning
`format`	`jsonl` (the default) or `csv`
`after`	Where to start: the `Plotwork-Next-Cursor` header of the export before
`actor`, `action`, `target`, `from`, `to`	The same filters as the log. `action` takes an action or a group such as `orgs.member`; `from` and `to` take ISO 8601 times.
`Plotwork-Next-Cursor`	The last event in this export. Send it as `after` next time.
`Plotwork-More`	`true` when more events are waiting after this export: ask again at once.

A cell in the CSV that a spreadsheet would run as a formula starts with ', because a diagram's name is text a member typed.

3. Connect a SIEM

In the organisation's Keys tab, create a key and choose "Audit log only: read and export it". That key reads the log and is refused everywhere else, so it cannot publish or delete.
Store the key in the SIEM's secret store.
Poll the export every few minutes. Keep the last Plotwork-Next-Cursor you saw, and send it as after. While Plotwork-More is true, ask again straight away.
Parse each line against the event schema (opens in a new tab).

SIEM	How it polls
Splunk	An HTTP input or a scripted input that runs the request above and keeps the cursor in a checkpoint
Datadog	A small job that runs the request and sends each line to the Logs intake
Microsoft Sentinel	A codeless connector or a logic app with a REST API poller, paging by the `after` parameter

A key's export is not recorded as an event, so polling does not fill the log with its own reads. The key's last use is on the Keys tab.

4. The event

Every event has the same shape, version 1. A field may be added; none is removed or changes meaning without a new version.

Field	Meaning
`version`	`1`
`id`	The event's id
`orgId`	The organisation's id
`at`	When it happened, as an ISO 8601 time in UTC
`action`	What happened, such as `orgs.member.role` (the list is below)
`actor.kind`	`user`, `key`, `ci` or `operator`
`actor.id`	The account id, the key id, or null for Plotwork support
`actor.name`	The email address or key name when it was recorded, "Plotwork support", or null once a deleted account is forgotten
`target.type`, `target.id`, `target.name`	What it was done to: its kind, its id, and its name or address
`metadata`	A few facts, such as `role`, `keepEditable`, `folder`, `scopes` or `reason`
`ip`	The network the request came from, or null
`userAgent`	The first 200 characters of the user agent, or null
`requestId`	The request id, which Plotwork support can look up

Group	Actions
Organisation	`orgs.org.create`, `orgs.org.rename`
Members	`orgs.member.add`, `orgs.member.remove`, `orgs.member.leave`, `orgs.member.role`, `orgs.owner.transfer`
Invitations	`orgs.invite.create`, `orgs.invite.revoke`, `orgs.invite.accept`
API keys	`orgs.key.create`, `orgs.key.reveal`, `orgs.key.revoke`
Diagrams	`orgs.diagram.publish`, `orgs.diagram.update`, `orgs.diagram.edit`, `orgs.diagram.restore`, `orgs.diagram.lock`, `orgs.diagram.unlock`, `orgs.diagram.delete`
Folder rules	`orgs.folder_rule.set`, `orgs.folder_rule.clear`
Look	`orgs.brand.set`, `orgs.brand.clear`, `orgs.icon.set`, `orgs.icon.delete`, `orgs.avatar.set`, `orgs.avatar.clear`, `orgs.style_rules.set`, `orgs.style_rules.clear`
Settings	`orgs.settings.editable`, `orgs.settings.publishing`
Members' public diagrams	`orgs.publishing.move`, `orgs.publishing.unpublish`
CI	`orgs.drift.report`
Contract	`orgs.contract.set`, `orgs.contract.end`
Integrations	`orgs.integration.create`, `orgs.integration.update`, `orgs.integration.delete`
The log itself	`orgs.audit.export`

5. How long events are kept

Plan	Kept
Free	Nothing is recorded
Pro	30 days
Enterprise	365 days, or the days the contract sets

A daily clean-up removes older events. When an organisation moves to a plan that keeps fewer days, the next clean-up removes what that plan does not keep. The log goes with the organisation. When an account is deleted, its email address is cleared from every log and its id stays.

Page	Why
Organisations	Roles, keys and who may do what
Single sign-on	The sign-in events this log records
Plans and billing	What Pro and Enterprise include
Enterprise rollout	Keys and CI across many repositories
Send audit events and drift to your tools	Push each event to Datadog, Dynatrace, Splunk, Microsoft Sentinel or a webhook
Privacy policy	What the log stores, and for how long
API reference	The read and export routes