Concepts

Audit Logs

Audit logs record administrative and security-relevant activity across your organization for review and investigation.

Overview

Audit logs record administrative and security-relevant activity across your organization: who did what, when, and whether it succeeded. Monospace writes an entry every time an account changes, an invitation is issued, workspace membership changes, or a schema migration is applied.

Administrators read the log through the system API to review activity, investigate changes, and support compliance reviews.

Recorded Activity

Every entry describes one action against one resource. Monospace records two resource types — user and schema — and the actions below.

User activity

Action	What triggers it
`user.create.v1`	A user account or service account is created.
`user.update.v1`	A user account or service account is changed, including a user editing their own profile or an administrator editing another user. Records the fields that changed.
`user.soft_delete.v1`	A user account or service account is removed.
`organization.invite_member.v1`	A new member is invited to the organization or a workspace. Records the invited email, the assigned roles, and the invitation's expiry.
`user.join_workspace.v1`	A user or service account is added to a workspace — directly, or by accepting a workspace invitation.
`user.remove_workspace.v1`	A member is removed from a workspace. One entry is recorded per member.
`user.invite_revoke.v1`	A pending invitation is revoked.
`user.invite_renew.v1`	A pending invitation is renewed with a new expiry.

Authentication activity

These cover the built-in password authentication method.

Action	What triggers it
`auth.login.v1`	A user signs in successfully. Records the auth method, session mode, and — when present — the user agent and referer.
`auth.login_failed.v1`	A sign-in attempt fails. Recorded with a `failure` outcome against the attempted email and a generic `reason` (such as `invalid_email_or_password`), so it never reveals whether the account exists.
`auth.logout.v1`	A user signs out and their refresh session is invalidated.
`auth.token_refresh.v1`	A user's access token is refreshed.
`auth.password_reset_request.v1`	A password reset is requested. A request for an unknown email is recorded with a `failure` outcome to prevent account enumeration.
`auth.password_reset_confirm.v1`	A password reset is completed with a valid token.
`auth.password_change.v1`	A signed-in user changes their own password.

Schema activity

Action	What triggers it
`schema.migration.v1`	A schema migration is applied to a workspace, recorded after it commits.

A migration groups one or more changes to your data model — for example, creating, renaming, or deleting a collection; adding a field, changing its type, or removing it; or defining a relation. The entry's payload lists each operation the migration applied.

Entry Structure

Every entry shares a common set of fields.

Field	Description
`id`	Unique identifier for the entry.
`timestamp`	When the activity occurred.
`action`	The versioned event type, such as `user.create.v1`.
`resourceType`	The kind of resource affected: `user`, `session`, or `schema`.
`resourceId`	Identifier of the affected resource. Empty for events that do not target a single resource, such as schema migrations.
`actorId`	The user who performed the action. Empty when the action is performed by the system or without a signed-in user.
`outcome`	The result: `success`, `partial_success`, or `failure`.
`workspaceId`	The workspace the activity belongs to, for workspace-scoped events.
`payload`	Action-specific detail, returned as native JSON. Its contents vary by `action`.

Action names carry a version suffix (.v1) so the structure of each event type stays stable for integrations.

A failure outcome is recorded when an operation does not complete — for example, an attempt to remove a workspace member that removes nothing.

Reading the Audit Log

Audit logs are read through the system API. Reading them requires the auditLog:read entitlement, which organization administrators have. See Access & Permissions for how entitlements are granted.

GET /api/system/audit-logs

The endpoint accepts the same query parameters as the rest of the API:

Parameter	Description
`fields`	The fields to return. Required — there is no implicit select-all, and an empty selection is rejected. See Field Selection.
`filter`	Return only entries matching a condition. See Filtering.
`sort`	Order the entries. See Sorting & Pagination.
`limit`	Maximum number of entries to return.
`offset`	Number of entries to skip, for pagination.

Every request must select fields — pass fields=* to return all of them, or name the ones you want, as shown below. Field names use the API spelling (resourceType, actorId, workspaceId), not the underlying column names.

Recent activity

Return the 50 most recent entries, newest first:

curl -g "https://example.monospace.io/api/system/audit-logs?fields=id,timestamp,action,resourceType,resourceId,actorId,outcome,workspaceId,payload&sort[0][timestamp][direction]=desc&limit=50" \
  -H "Authorization: Bearer YOUR_API_KEY"

const response = await fetch(
  'https://example.monospace.io/api/system/audit-logs?fields=id,timestamp,action,resourceType,resourceId,actorId,outcome,workspaceId,payload&sort[0][timestamp][direction]=desc&limit=50',
  {
    headers: {
      Authorization: 'Bearer YOUR_API_KEY',
    },
  },
);

const { data } = await response.json();

Each matching entry is returned under data:

response.json

{
  "data": [
    {
      "id": "0a9e7c1b-6d2f-4c8a-9f3e-1b2c3d4e5f6a",
      "timestamp": "2026-06-23T10:14:22Z",
      "action": "user.create.v1",
      "resourceType": "user",
      "resourceId": "2c1a4e9b-8d7f-4a6b-9c0e-5f4d3a2b1c0d",
      "actorId": "7f6b2d10-3e4a-4b5c-8d9e-0a1b2c3d4e5f",
      "outcome": "success",
      "workspaceId": null,
      "payload": { "email": "alex@example.com" }
    }
  ]
}

Filter by action

Return only schema migrations:

curl

curl -g "https://example.monospace.io/api/system/audit-logs?fields=timestamp,action,resourceType,workspaceId&filter[action][_eq]=schema.migration.v1" \
  -H "Authorization: Bearer YOUR_API_KEY"

Filter by actor

Return every action a specific user performed:

curl

curl -g "https://example.monospace.io/api/system/audit-logs?fields=timestamp,action,resourceType,resourceId,outcome&filter[actorId][_eq]=7f6b2d10-3e4a-4b5c-8d9e-0a1b2c3d4e5f" \
  -H "Authorization: Bearer YOUR_API_KEY"

Failed operations

Return only entries that did not succeed:

curl

curl -g "https://example.monospace.io/api/system/audit-logs?fields=timestamp,action,resourceType,resourceId,outcome&filter[outcome][_eq]=failure" \
  -H "Authorization: Bearer YOUR_API_KEY"