Audit logs

Plat5 keeps an audit log for every organization and every person. The gateway writes it, so your services don’t.

What’s recorded

Each event is one request:

• Who: the member (or person) whose credential was used, and which credential.
• What: the service, method, route and path ids.
• From where: IP and user agent.
• How it ended: the outcome, including 403s.
• What changed: if your service says so, in one response header (below).

Writes (POST, PUT, PATCH, DELETE) are recorded by default. A route can opt a read in or a write out with audit: true or audit: false.

Recorded first

The gateway records the request before forwarding it. If it can’t, the request is refused with a 503 and your service is never called, so a change can’t happen without its record. The outcome is added after the response. Until then the event is pending, which never means success.

Which log

Route scope	Log
organization, member	The organization’s
user	The person’s own. A change to something an organization owns (creating it, joining it, opening a session) is in that organization’s log too
public	None

Reading

GET /org/audit-events
X-API-Key: <member key or session>

Newest first, filterable by member, route, method, outcome, path id, the id a create produced, and time. Organization admins read it with the org:audit:read permission, so the audit log page enterprise customers ask for is a page in your app over this API. People read their own log at GET /user/audit-events.

What your service adds

Set response headers to say what changed. The gateway stores them and removes them before the response leaves.

X-Plat5-Audit-Details: {"name":{"from":"Launch","to":"Launch v2"}}
X-Plat5-Audit-Created: 01JD8X3K7Q2M9V4T6R8Y0B1C2D

X-Plat5-Audit-Created is the id a create produced, so “who created this project?” is a lookup by the project’s id.

Off

Audit is on or off for the whole deployment. AUDIT_ENABLED=false turns it off.

More: audit.md.