Talewright Docs Open the app

Audit trail

Summary

Talewright records an audit event for every change to accounts, sessions, organizations, workspaces, members, invitations, credentials, files, folders, tags, uploads, statuses, fields and library proposals. An event says who did what to which thing, when, where, and whether an API key or a connected app did it. This page says what is recorded, who can read it and where, and lists every action name with what triggers it.

The part of the trail people read in the product is credential activity: what was done with one API key or one connected app.

Who can do what

ActionOwnerAdminMemberSigned-in personCredential
Read the activity of your own API key or connected appYesYesYesYesNo (browser only)
Read the activity of another member's API key or connected app in the organizationYesYesNoYesNo (browser only)
Read the whole audit trail of an organizationNoNoNoNoNo
Change or delete an audit eventNoNoNoNoNo
  • Reading activity is the capability credential.organization.activity. It needs a browser session. A valid bearer token gets 403 FORBIDDEN with reason SESSION_REQUIRED.
  • There is no page and no API operation that lists the whole trail. Talewright support can read it.

How it works

What an event holds

  • When it happened (occurredAt).
  • Who did it: the person. Events recorded by the system, such as a purge after the trash period, have no person.
  • The action, written <area>.<verb>, such as file.updated.
  • The target: its type (such as file or folder) and its ID.
  • Where: the organization and, for things inside one, the workspace. An event about a file of the organization folder (the API's library) has an organization and no workspace.
  • The request: the ID of the request that made the change. It is the same requestID an error body carries and the x-request-id response header.
  • The credential: when the request was made with an API key or a connected app, the event carries the credential's ID and kind (api_key or connected_app).
  • A few details: identifiers, counts and fixed values, such as the number of files a folder took to the trash, or the reason a key was revoked.

What an event never holds

  • Passwords, API keys, tokens, link tokens or signed URLs.
  • Email addresses.
  • People's names.
  • The names of statuses, fields and options. An event names a status, a field or an option by its ID. A rename is recorded without the old or the new name.
  • File content.

Deleting an account therefore leaves no personal data behind in the trail.

Rules

  • An event is recorded together with the change it describes. If the change does not happen, no event exists. If the event exists, the change happened.
  • Events are never changed and never deleted.
  • Events outlive what they describe. Purging a file, a workspace or an organization keeps its events.
  • A request that is refused and changes nothing records nothing.
  • Reading records nothing, with one exception: asking for a ZIP download records files.archive_downloaded.
  • One request can record several events. Setting a status on 100 files records 100 file.status_changed events.

Credential activity

  • Activity lists the events recorded during requests made with one credential, newest first.
  • Each entry has an id, occurredAt, the action, the targetType, the targetID and the workspace (ID and name).
  • workspace is null for events without a workspace, such as organization folder files, and for a workspace that has since been deleted.
  • Activity lists what was done with the credential. Creating, rotating and revoking the credential happen in a browser session, so they are not in its own activity.
  • Verification of an upload finishes in the background, after the request that completed it. Its events carry the request and the credential of that completing request. An upload through a key therefore shows upload.created, upload.completed and then file.created, file.version_created or, when verification refused it, upload.rejected.
  • An upload whose verification stopped without an answer is rejected later by the system. That upload.rejected is in no credential's activity.
  • A revoked credential keeps its activity.
  • A credential that was never used has no activity.

In the app

  • Settings > Credentials lists your API keys. Each row has the button "Activity" (named "Activity of {name}").
  • Settings > Connected apps lists your connected apps, each with "Activity".
  • Organization settings > Key management lists every member's API keys and connected apps for owners and admins, each with "Activity".
  • "Activity" opens a side sheet titled "Activity of {name}".
  • The sheet lists each action in plain words, with its workspace and time. The words come from the action name: folder.created reads "Folder created", file.status_changed reads "File status changed".
  • A credential that was never used shows "Nothing has been done with it yet."
  • "Load more" shows older entries.
  • When the list cannot be read, the sheet says "Could not load the activity."

For agents

OperationCapabilityAccess
GET /v1/organizations/{organizationID}/credentials/{credentialID}/activitycredential.organization.activityBrowser session only
  • Query: cursor and limit (1 to 100, default 50).
  • Answer: { "items": [...], "nextCursor": string | null }, newest first.
  • There is no MCP tool for activity, and no operation for the rest of the trail.
  • An agent cannot read its own activity. It can read what it acts as with credential_read (GET /v1/credential).

One entry:

{
  "id": "0192f0a1-6f2e-7c11-9a55-2f6d0c1e7b90",
  "occurredAt": "2026-11-14T09:12:44Z",
  "action": "folder.created",
  "targetType": "folder",
  "targetID": "0192f0a1-6f2d-7a40-8a13-9b1c4d2e6f77",
  "workspace": { "id": "0192e7c4-11aa-7b02-b6f0-5d7a1c9e3f21", "name": "Keystone Main" }
}

Every action

"By" says whose action it is: a person, or the system when nobody is named. Target types are user, session, organization, workspace, invitation, export, file, folder, tag, upload, file_status, file_field, library_proposal and credential.

Accounts

ActionTargetByTrigger
user.signed_upuserPersonA new account is created at sign-up.
user.verification_requesteduserSystemA new verification email is requested for an unverified account.
user.email_verifieduserPersonThe email is verified from the emailed link. The event notes whether a new password was set and how many sessions ended.
user.password_reset_requesteduserSystemA password reset email is requested for an existing account.
user.password_resetuserPersonA new password is set from a reset link. The event notes how many sessions ended.
user.password_changeduserPersonThe password is changed in the app. The event notes how many other sessions ended.
user.profile_updateduserPersonThe name is changed.
user.email_change_requesteduserPersonAn email change is started.
user.email_change_cancelleduserPersonA pending email change is cancelled.
user.email_changeduserPersonAn email change is confirmed from the link sent to the new address.
user.other_sessions_revokeduserPerson"Sign out other sessions" is used. The event notes how many ended.
user.deleteduserPerson or systemThe account is deleted. By the system with reason never_verified: the account never verified its email and was still empty 30 days after sign-up.

Sessions

ActionTargetByTrigger
session.createdsessionPersonA session starts. The event notes how: by password at sign-in, at sign-up, or from the email verification link.
session.signed_outsessionPersonThe person signs out.
session.revokedsessionPersonThe person ends one of their sessions from the session list. With reason replaced: a new session started in a browser that carried this one, and the person named is the one who signed in.

Organizations and workspaces

ActionTargetByTrigger
organization.createdorganizationPersonAn organization is created.
organization.renamedorganizationPersonThe organization is renamed.
organization.deletedorganizationPerson or systemAn owner deletes the organization. It stays restorable for 30 days. By the system with reason never_verified: the empty organization of an account that was removed for never verifying its email.
organization.restoredorganizationPersonAn owner restores a deleted organization.
organization.purgedorganizationSystemA deleted organization is removed for good after its 30 days.
workspace.createdworkspacePersonA workspace is created, including the first workspace made with a new organization.
workspace.renamedworkspacePersonA workspace is renamed.
workspace.deletedworkspacePersonA workspace is deleted. It stays restorable for 30 days.
workspace.restoredworkspacePersonA deleted workspace is restored.
workspace.purgedworkspaceSystemA deleted workspace is removed for good after its 30 days.

Members and invitations

ActionTargetByTrigger
member.role_changeduserPersonA member's organization role is changed. The event notes the old and the new role and how many of the member's invitations were withdrawn.
member.removeduserPersonA member is removed from the organization.
member.leftuserPersonA member leaves the organization.
workspace_member.updateduserPersonA member is added to a workspace, or their workspace role is changed.
workspace_member.removeduserPersonA member's explicit workspace membership is removed.
invitation.createdinvitationPersonSomeone is invited, or an invitation is resent. The event notes the role, the number of workspaces and whether it was a resend.
invitation.revokedinvitationPersonAn invitation is revoked.
invitation.acceptedinvitationPersonAn invitation is accepted.

Export

ActionTargetByTrigger
export.requestedexportPersonAn export of the organization is requested.
export.completedexportSystemThe export is ready. The event notes the number of files and bytes.
export.failedexportSystemThe export failed.

Files

ActionTargetByTrigger
file.createdfilePerson (the uploader)An upload passed verification and became a new file.
file.version_createdfilePerson (the uploader)An upload passed verification and became a new version of an existing file. The event notes the version number.
file.updatedfilePersonA file is renamed, moved, retagged or described, or its field values change. The event notes which details changed, and the proposal when the change came from applying a library proposal. Setting one field on many files records one event per file.
file.trashedfilePersonA file is moved to the trash on its own.
file.restoredfilePersonA file is restored from the trash on its own. Who may restore, and when a restore is refused, is in Trash and restore.
file.purge_requestedfilePersonAn owner or admin deletes a trashed file for good.
file.purgedfileSystemA file is removed for good, after a request or after its trash period.
file.status_changedfilePersonA file's status is set or cleared. One event per file. The event notes the status and whether a public link stopped.
file.visibility_changedfilePersonA file's general access is changed to public or restricted.
files.archive_downloadedfolder, workspace or organizationPersonA ZIP download is requested. The target is the folder when exactly one folder and nothing else is downloaded, otherwise the workspace or, for the organization folder, the organization. The event notes the number of folders, files and bytes.

Folders, trash and tags

ActionTargetByTrigger
folder.createdfolderPersonA folder is created. Also for each folder that applying a proposal's move creates.
folder.updatedfolderPersonA folder is renamed or moved. The event notes which.
folder.trashedfolderPersonA folder is moved to the trash with its content. The event notes how many files went along.
folder.restoredfolderPersonA folder is restored with what it took along. The event notes how many files came back.
folder.purge_requestedfolderPersonAn owner or admin deletes a trashed folder for good.
folder.purgedfolderSystemA trashed folder is removed for good once its files are purged.
folder.visibility_changedfolderPersonA folder's general access is changed. The event notes how many public links started and stopped.
trash.emptiedworkspace or organizationPersonAn owner or admin empties the trash. The event notes how many files.
tag.renamedtagPersonA tag is renamed. The event notes how many files carry it.
tag.deletedtagPersonA tag is deleted. The event notes how many files carried it.

Uploads

ActionTargetByTrigger
upload.createduploadPersonAn upload is started. The event notes the declared size, the type and whether it replaces a file.
upload.completeduploadPersonThe uploader hands the bytes over for verification.
upload.cancelleduploadPersonThe uploader cancels a pending upload.
upload.rejecteduploadSystemVerification refused the upload. The event notes the reject reason.

Statuses and fields

ActionTargetByTrigger
file_status.createdfile_statusPersonA status is added to the list of a workspace or the organization folder. The event notes whether it allows public use, not its name.
file_status.updatedfile_statusPersonA status is renamed, its "allows public use" changes, or it becomes or stops being the default. The event notes the new "allows public use" and default settings when they were sent, and how many public links stopped. It holds no name.
file_status.deletedfile_statusPersonA status is deleted. The event notes how many public links stopped.
file_status.reorderedworkspace or organizationPersonThe statuses of a workspace, or for the organization folder the organization, are put in a new order.
file_field.createdfile_fieldPersonA field is added to a workspace or the organization folder. The event notes its kind (text, number, date, select or multiSelect), not its name.
file_field.updatedfile_fieldPersonA field is renamed, or one of its choices is added, renamed, deleted or reordered. A rename is noted as renamed: true, without the name. A change to a choice is noted with the choice's ID.
file_field.deletedfile_fieldPersonA field is deleted. The event notes how many files lost a value.
file_field.reorderedworkspace or organizationPersonThe fields of a workspace, or for the organization folder the organization, are put in a new order.

Library proposals

ActionTargetByTrigger
library_proposal.createdlibrary_proposalPersonA proposal is created. The event notes the number of items.
library_proposal.appliedlibrary_proposalPersonA person applies items. The event notes how many applied and how many were stale. Each applied item also records its own file.updated.
library_proposal.rejectedlibrary_proposalPersonItems are rejected. The event notes how many.

Credentials

ActionTargetByTrigger
api_key.createdcredentialPersonAn API key is created. The event notes its scopes, the number of workspaces and its lifetime in days.
api_key.rotatedcredentialPersonAn API key's secret is replaced. The event notes the overlap in hours.
api_key.revokedcredentialPerson or systemAn API key is revoked. The event notes the reason and the key's member.
connected_app.createdcredentialPersonAn app is connected. Every connection has its own event, also a second one of the same app for the same member and organization. The event notes the app's client ID, the scopes, the number of workspaces and the lifetime.
connected_app.revokedcredentialPerson or systemA connected app is disconnected or revoked. The event notes the reason and the app's member.

Revocation reasons, for api_key.revoked and connected_app.revoked:

ReasonWhenBy
userThe member revoked or disconnected it, or the app revoked its own token. An owner or admin revoking their own credential also counts as user.Person
adminAn owner or admin revoked another member's credential.Person
membership_removedThe member left the organization or was removed from it.System
password_resetThe member reset their password from an emailed link, or set a new password when verifying their email in another browser.System
password_changedThe member changed their password in the app.System
user_deletedThe member deleted their account.System
refresh_reusedA connected app's refresh token that was already used was presented again.System
code_reusedThe authorization code that made a connected app was presented again.System

Edge cases

  • An API key creates a folder, then the key is revoked. The folder's folder.created stays in the key's activity. Revoking hides nothing.
  • A member's key is revoked because they were removed. The event has no person: the removal did it. The removal itself is member.removed, by the person who removed them.
  • A connected app is connected a second time. One event: connected_app.created for the new connection. The earlier connection is not touched. Each connection has its own activity.
  • A folder with 300 files is trashed. One folder.trashed noting 300 files, not 300 file.trashed events.
  • A status is set on 100 files in one request. 100 file.status_changed events with the same request ID.
  • An agent's proposal is applied by a person. library_proposal.created is in the agent's activity. library_proposal.applied and the resulting file.updated events are the person's, made in a browser session, so they are not in the agent's activity.
  • An upload through a key is rejected. upload.created, upload.completed and upload.rejected are in the key's activity. The rejection has no person: verification made it.
  • An upload is started with a key and completed in the browser. The events of verification follow the completing request, so file.created is not in the key's activity.
  • A workspace is deleted. Activity entries that happened in it stay, with workspace: null.
  • An organization is purged. Its events stay. Its credentials are gone, so nobody can open their activity any more.
  • A request is refused. No event. A 403, 404, 409 or 422 that changes nothing leaves no trace in the trail.
  • A used authorization code or refresh token is presented again. The request is refused, and the connected app is revoked. That revocation is recorded, with reason code_reused or refresh_reused.
  • MCP tool calls. Each tool call records its events with the ID of the MCP request that carried it.
  • A person hides a duplicate warning, or shows it again. No event. It is the person's own preference and changes no file.
  • A person sends feedback. No event. The report itself holds who sent it and when, until the sender deletes their account.

Errors

CodeStatusWhenWhat to do
UNAUTHENTICATED401No session.Sign in.
FORBIDDEN SESSION_REQUIRED403A bearer token asked for activity.Read activity in the web app.
NOT_FOUND404The credential is unknown, belongs to another organization, or belongs to another member and you are not an owner or admin.Check the ID and your role.
VALIDATION_FAILED422An invalid cursor or limit.Use the nextCursor you were given and a limit of 1 to 100.

Limits

LimitValue
Activity entries per page1 to 100, default 50
Details kept with one eventSmall: identifiers, counts and fixed values only
How long events are keptThey are not deleted

Questions and answers

Where do I see what my agent did? Open Settings > Credentials (for an API key) or Settings > Connected apps, and press "Activity" on its row.

Can an owner see what a member's agent did? Yes. Owners and admins open "Activity" on any credential under Organization settings > Key management.

Can a member see what another member's agent did? No. The answer is 404.

Is there a full audit log I can browse or export? No. The product shows credential activity only. The organization export does not contain the trail.

Can an agent read the audit trail? No. Activity needs a browser session.

Does the trail show who made a change when an agent made it? Both. The event names the member the credential acts for, and the credential's ID and kind.

Does reading or downloading a file leave an event? Reading does not. Asking for a ZIP download records files.archive_downloaded. Single signed URLs are not recorded.

Can an event be edited or removed? No, by nobody.

Do events survive deleting a file, a workspace or the organization? Yes.

Does the trail contain personal data? It contains IDs of people, never their names or email addresses.

Does a key's activity show the file an upload made? Yes. The file is created after verification, in the background, and its file.created carries the credential that completed the upload. The activity shows upload.created, upload.completed and file.created.

How do I match an error to an event? By request ID. The requestID of a response is the request ID of the events that request recorded.