Audit logs_

Appwrite provides audit logs to help detect anomalies and investigate security incidents.

3 min read

All Appwrite products, like Authentication, Databases, Storage, Functions, and Messaging, provide detailed audit logs. Audit logs are important in detecting and responding to security incidents. Through audit logs, you can detect incidents through anomalous activities, trace the source of security incidents, and understand the scope of users affected so you can respond more quickly and effectively.

Access audit logs

You can access audit logs for different products under the Activity tab where applicable. Logs are available for tables, rows, and individual users.

Format

Audit log entries under the Activity tab has the following structure. Each entry describes an event.

Column	Description
User	Name of the user that performed the event.
Event	The name of the event.
Location	The physical of the user when they performed the action.
IP	The IP of the user when they performed an action.
Date	The date and time of the event.
Reason	Why the request was made, when the client sent one. See Record a reason.

Record a reason

Send the X-Appwrite-Reason header with an API request to record why it was made. The reason appears in the Reason column of the Activity tab, next to the event it explains, so you can review changes made by AI agents, scripts, and teammates later.

HTTP

DELETE /v1/functions/checkout-legacy HTTP/1.1
X-Appwrite-Project: <PROJECT_ID>
X-Appwrite-Key: <API_KEY>
X-Appwrite-Reason: Moved to SSR endpoint /api/checkout in storefront site

A reason is one line of text of up to 256 characters. The header value is percent-decoded, so send it encoded with encodeURIComponent (or your language's equivalent). That covers any language, and a literal % as %25. Plain ASCII text without % can be sent as it is.

A request fails with general_argument_invalid before it runs when its reason is longer, isn't valid UTF-8, or contains control characters such as line breaks, tabs or terminal escapes, or Unicode bidirectional override characters.

From the CLI

Pass --reason to any Appwrite CLI command, or set the APPWRITE_REASON environment variable for a whole shell session or CI job. The CLI encodes the reason and sends it with every request the command makes.

Bash

appwrite push functions --reason "Release 2.4: move checkout to the storefront site"

From the MCP server

The Appwrite MCP server asks the AI agent for a reason with every change it makes and records it on the request. Changes an agent makes show up in Activity with the reason the agent gave.

Retention

GDPR data retention rules require any personal data that is collected or processed to be kept only for as long as data are required to achieve the purpose for which the information was collected. For this reason, audit logs are retained for only 7 days for Pro organizations and 1 hour for Free organizations.

Was this page helpful?

Share what worked or what we should fix. Once approved, our agents automatically apply suggested updates to the docs.