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
| Action | Owner | Admin | Member | Signed-in person | Credential |
|---|---|---|---|---|---|
| Read the activity of your own API key or connected app | Yes | Yes | Yes | Yes | No (browser only) |
| Read the activity of another member's API key or connected app in the organization | Yes | Yes | No | Yes | No (browser only) |
| Read the whole audit trail of an organization | No | No | No | No | No |
| Change or delete an audit event | No | No | No | No | No |
- Reading activity is the capability
credential.organization.activity. It needs a browser session. A valid bearer token gets403 FORBIDDENwith reasonSESSION_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 asfile.updated. - The target: its type (such as
fileorfolder) 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
requestIDan error body carries and thex-request-idresponse 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_keyorconnected_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_changedevents.
Credential activity
- Activity lists the events recorded during requests made with one credential, newest first.
- Each entry has an
id,occurredAt, theaction, thetargetType, thetargetIDand theworkspace(ID and name). workspaceisnullfor 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.completedand thenfile.created,file.version_createdor, when verification refused it,upload.rejected. - An upload whose verification stopped without an answer is rejected later by
the system. That
upload.rejectedis 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.createdreads "Folder created",file.status_changedreads "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
| Operation | Capability | Access |
|---|---|---|
GET /v1/organizations/{organizationID}/credentials/{credentialID}/activity | credential.organization.activity | Browser session only |
- Query:
cursorandlimit(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
| Action | Target | By | Trigger |
|---|---|---|---|
user.signed_up | user | Person | A new account is created at sign-up. |
user.verification_requested | user | System | A new verification email is requested for an unverified account. |
user.email_verified | user | Person | The email is verified from the emailed link. The event notes whether a new password was set and how many sessions ended. |
user.password_reset_requested | user | System | A password reset email is requested for an existing account. |
user.password_reset | user | Person | A new password is set from a reset link. The event notes how many sessions ended. |
user.password_changed | user | Person | The password is changed in the app. The event notes how many other sessions ended. |
user.profile_updated | user | Person | The name is changed. |
user.email_change_requested | user | Person | An email change is started. |
user.email_change_cancelled | user | Person | A pending email change is cancelled. |
user.email_changed | user | Person | An email change is confirmed from the link sent to the new address. |
user.other_sessions_revoked | user | Person | "Sign out other sessions" is used. The event notes how many ended. |
user.deleted | user | Person or system | The 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
| Action | Target | By | Trigger |
|---|---|---|---|
session.created | session | Person | A session starts. The event notes how: by password at sign-in, at sign-up, or from the email verification link. |
session.signed_out | session | Person | The person signs out. |
session.revoked | session | Person | The 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
| Action | Target | By | Trigger |
|---|---|---|---|
organization.created | organization | Person | An organization is created. |
organization.renamed | organization | Person | The organization is renamed. |
organization.deleted | organization | Person or system | An 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.restored | organization | Person | An owner restores a deleted organization. |
organization.purged | organization | System | A deleted organization is removed for good after its 30 days. |
workspace.created | workspace | Person | A workspace is created, including the first workspace made with a new organization. |
workspace.renamed | workspace | Person | A workspace is renamed. |
workspace.deleted | workspace | Person | A workspace is deleted. It stays restorable for 30 days. |
workspace.restored | workspace | Person | A deleted workspace is restored. |
workspace.purged | workspace | System | A deleted workspace is removed for good after its 30 days. |
Members and invitations
| Action | Target | By | Trigger |
|---|---|---|---|
member.role_changed | user | Person | A 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.removed | user | Person | A member is removed from the organization. |
member.left | user | Person | A member leaves the organization. |
workspace_member.updated | user | Person | A member is added to a workspace, or their workspace role is changed. |
workspace_member.removed | user | Person | A member's explicit workspace membership is removed. |
invitation.created | invitation | Person | Someone is invited, or an invitation is resent. The event notes the role, the number of workspaces and whether it was a resend. |
invitation.revoked | invitation | Person | An invitation is revoked. |
invitation.accepted | invitation | Person | An invitation is accepted. |
Export
| Action | Target | By | Trigger |
|---|---|---|---|
export.requested | export | Person | An export of the organization is requested. |
export.completed | export | System | The export is ready. The event notes the number of files and bytes. |
export.failed | export | System | The export failed. |
Files
| Action | Target | By | Trigger |
|---|---|---|---|
file.created | file | Person (the uploader) | An upload passed verification and became a new file. |
file.version_created | file | Person (the uploader) | An upload passed verification and became a new version of an existing file. The event notes the version number. |
file.updated | file | Person | A 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.trashed | file | Person | A file is moved to the trash on its own. |
file.restored | file | Person | A 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_requested | file | Person | An owner or admin deletes a trashed file for good. |
file.purged | file | System | A file is removed for good, after a request or after its trash period. |
file.status_changed | file | Person | A file's status is set or cleared. One event per file. The event notes the status and whether a public link stopped. |
file.visibility_changed | file | Person | A file's general access is changed to public or restricted. |
files.archive_downloaded | folder, workspace or organization | Person | A 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
| Action | Target | By | Trigger |
|---|---|---|---|
folder.created | folder | Person | A folder is created. Also for each folder that applying a proposal's move creates. |
folder.updated | folder | Person | A folder is renamed or moved. The event notes which. |
folder.trashed | folder | Person | A folder is moved to the trash with its content. The event notes how many files went along. |
folder.restored | folder | Person | A folder is restored with what it took along. The event notes how many files came back. |
folder.purge_requested | folder | Person | An owner or admin deletes a trashed folder for good. |
folder.purged | folder | System | A trashed folder is removed for good once its files are purged. |
folder.visibility_changed | folder | Person | A folder's general access is changed. The event notes how many public links started and stopped. |
trash.emptied | workspace or organization | Person | An owner or admin empties the trash. The event notes how many files. |
tag.renamed | tag | Person | A tag is renamed. The event notes how many files carry it. |
tag.deleted | tag | Person | A tag is deleted. The event notes how many files carried it. |
Uploads
| Action | Target | By | Trigger |
|---|---|---|---|
upload.created | upload | Person | An upload is started. The event notes the declared size, the type and whether it replaces a file. |
upload.completed | upload | Person | The uploader hands the bytes over for verification. |
upload.cancelled | upload | Person | The uploader cancels a pending upload. |
upload.rejected | upload | System | Verification refused the upload. The event notes the reject reason. |
Statuses and fields
| Action | Target | By | Trigger |
|---|---|---|---|
file_status.created | file_status | Person | A 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.updated | file_status | Person | A 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.deleted | file_status | Person | A status is deleted. The event notes how many public links stopped. |
file_status.reordered | workspace or organization | Person | The statuses of a workspace, or for the organization folder the organization, are put in a new order. |
file_field.created | file_field | Person | A 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.updated | file_field | Person | A 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.deleted | file_field | Person | A field is deleted. The event notes how many files lost a value. |
file_field.reordered | workspace or organization | Person | The fields of a workspace, or for the organization folder the organization, are put in a new order. |
Library proposals
| Action | Target | By | Trigger |
|---|---|---|---|
library_proposal.created | library_proposal | Person | A proposal is created. The event notes the number of items. |
library_proposal.applied | library_proposal | Person | A 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.rejected | library_proposal | Person | Items are rejected. The event notes how many. |
Credentials
| Action | Target | By | Trigger |
|---|---|---|---|
api_key.created | credential | Person | An API key is created. The event notes its scopes, the number of workspaces and its lifetime in days. |
api_key.rotated | credential | Person | An API key's secret is replaced. The event notes the overlap in hours. |
api_key.revoked | credential | Person or system | An API key is revoked. The event notes the reason and the key's member. |
connected_app.created | credential | Person | An 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.revoked | credential | Person or system | A 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:
| Reason | When | By |
|---|---|---|
user | The 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 |
admin | An owner or admin revoked another member's credential. | Person |
membership_removed | The member left the organization or was removed from it. | System |
password_reset | The member reset their password from an emailed link, or set a new password when verifying their email in another browser. | System |
password_changed | The member changed their password in the app. | System |
user_deleted | The member deleted their account. | System |
refresh_reused | A connected app's refresh token that was already used was presented again. | System |
code_reused | The 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.createdstays 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.createdfor the new connection. The earlier connection is not touched. Each connection has its own activity. - A folder with 300 files is trashed. One
folder.trashednoting 300 files, not 300file.trashedevents. - A status is set on 100 files in one request. 100
file.status_changedevents with the same request ID. - An agent's proposal is applied by a person.
library_proposal.createdis in the agent's activity.library_proposal.appliedand the resultingfile.updatedevents 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.completedandupload.rejectedare 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.createdis 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,409or422that 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_reusedorrefresh_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
| Code | Status | When | What to do |
|---|---|---|---|
UNAUTHENTICATED | 401 | No session. | Sign in. |
FORBIDDEN SESSION_REQUIRED | 403 | A bearer token asked for activity. | Read activity in the web app. |
NOT_FOUND | 404 | The 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_FAILED | 422 | An invalid cursor or limit. | Use the nextCursor you were given and a limit of 1 to 100. |
Limits
| Limit | Value |
|---|---|
| Activity entries per page | 1 to 100, default 50 |
| Details kept with one event | Small: identifiers, counts and fixed values only |
| How long events are kept | They 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.