# 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 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

| Operation | Capability | Access |
| --- | --- | --- |
| `GET /v1/organizations/{organizationID}/credentials/{credentialID}/activity` | `credential.organization.activity` | Browser 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:

```json
{
  "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](../files/trash.md#the-restore-rule). |
| `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.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

| 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.

## Related pages

- [Credentials and scopes](../agents/credentials.md)
- [Connected apps](../agents/connected-apps.md)
- [Roles and permissions](permissions.md)
- [Errors](errors.md)
- [Glossary](glossary.md)

