Audit log
What the workspace audit log records, how to read an event, and how to use it to answer who changed what and why a request was denied.
The audit log is a durable, read-only record of workspace operations and authorization decisions, shown newest first under Settings › Audit log.
Prerequisites
- The
workspace.audit.readpermission. Owners and Administrators have it; Members and Viewers do not, and the Settings entry is hidden for them.
What an event records
Each event is shown as a card with the action as its heading, the local timestamp and relative time beneath it, and an outcome badge on the right. The card lists four fields, plus a Structured details expander with the raw event ID, action, principal kind, and metadata.
| Field | What it contains |
|---|---|
| When | The time the event occurred, shown in your local time and as a relative time. |
| Request | The HTTP request ID for request-backed events, or a synthetic ID for non-request events such as database triggers and operator actions. Use HTTP request IDs to correlate with support reports and logs. |
| Principal kind | user, service, sandbox, or personal-access-token: whether a signed-in person, a bot or operator tool, a session sandbox, or a member's personal access token acted. |
| Actor | A snapshot of the acting user ID, the acting service, or both (a service acting on behalf of a user shows both). A personal access token shows the token ID and its owner. |
| Action | The operation, for example workspace.member_role_updated. |
| Resource | The resource type and, when there is one, its ID (for example user / <id> or http_route / /sessions). |
| Target user | The user the operation was about, appended to the resource as Target user <id> when present. |
| Reason | A short reason code, such as member_role_updated, member_status_unchanged, or the denial code for a refused request. |
| Outcome | Operation outcomes: Applied, No change, Denied, or Rejected; authorization decisions: Allowed or Denied. An allowed decision does not establish that an operation succeeded. |
| Metadata | Structured details specific to the action, shown as JSON under Structured details. |
Actor and target values are snapshots taken when the event was written. They do not change if the user is later renamed or merged.
Which operations are recorded
The control plane writes these event families today:
| Action | Shown as | When it is written |
|---|---|---|
workspace.member_role_updated | Member role updated | A member's role is changed from Settings › Workspace access. Outcome is Applied, or No change with reason member_role_unchanged when the role was already set. Metadata records the role before, requested, and after. |
workspace.member_status_updated | Member status updated | A member is suspended or restored. Outcome is Applied, or No change with reason member_status_unchanged. Metadata records the suspension state before, requested, and after. |
workspace.default_role_assigned | Default role assigned | A default workspace role was assigned. |
workspace.user_merged | Users merged | A merge of two user records. A user with workspace.members.merge (an Owner, an Administrator, or a custom role granted it) merged accounts from Settings › Workspace access (principal user, reason member_merge), or an operator ran the merge command (principal service, actor operator-cli, reason operator_merge). The resource is the kept user and the target user is the merged-in user. A merge refused at write time is recorded with result denied (reason actor_authorization_changed) or rejected (reason preconditions_changed, source_changed, or identity_conflict), and changed nothing. |
workspace.admission_policy_updated | Sign-in allowlist updated | An Owner or Administrator saved Settings › Workspace access › Who can sign in. Outcome is Applied, No change, Denied (reason actor_authorization_changed), or Rejected (reason conflict or unavailable). Metadata records the managed rules before and after, the expected and resulting revision, and a deployment fingerprint; rule values can include email addresses. Older events named workspace.admission_policy_maintenance (Sign-in allowlist maintenance) come from a write freeze that has been removed; nothing writes them now. |
workspace.personal_access_token_policy_updated | Access token policy updated | A holder of workspace.personal_access_tokens.manage saved Settings › Access token policy. Metadata records the policy before, the expected revision, and the policy after. |
team.created, team.updated, team.archived, team.restored | Team created/updated/archived/restored | A team was created or its details or archive state changed. |
team.member_added, team.member_role_changed, team.member_removed, team.member_joined | Team member added/role changed/removed/joined | Team membership changed. |
team.grant_added | Team repository grant added | A named-repository or installation-wide grant was added to a team. |
team.grant_removed | Team repository grant removed | A team repository grant was removed. This does not prove already-issued source-control credentials were revoked. |
team.secret_set | Team secret set | Team secrets were written. Metadata identifies keys, not secret values. |
team.secret_deleted | Team secret deleted | A team secret was deleted. |
session.created_private | Private session created | A session was created with Private visibility. |
session.visibility_changed | Session visibility changed | Session visibility changed; this is not an ownership transfer. |
session.collaborator_added | Session collaborator added | An explicit private-session collaborator was added. |
session.collaborator_removed | Session collaborator removed | An explicit private-session collaborator was removed. |
session.private_break_glass | Private session break-glass read | A workspace Owner read a private session without being its owner or collaborator. This does not grant collaboration or sandbox access. |
memory.personal_read | Personal memory read by an agent | An agent's memory search or read returned personal memories, which happens only on the session owner's own prompt. The resource is the session, the target is the owner, and metadata lists the memory IDs, never their content. |
automation.executor_changed | Automation executor changed | An authorized team lead or workspace Administrator/Owner reassigned an automation's executor. Metadata records the before/after user IDs; team ownership is unchanged. |
personal_access_token.created, personal_access_token.revoked | Personal access token created/revoked | A member issued or revoked one of their personal access tokens, or an administrator revoked a member's token. The actor is whoever acted, the resource is personal_access_token / <id>, and the target user is the token's owner. Metadata records the token's name, display prefix, permissions, and expiry, never the token itself. |
authorization.request_denied | Authorization denied | An authenticated request was refused by authorization. The resource is the HTTP route, the reason is the denial code, and metadata includes the HTTP method, path, and status; the failed permission and effective permissions appear when available. Authorization writes are best-effort, so some denials may be missing. |
authorization.request_allowed | Authorization allowed | A request passed authorization on a management-permission-gated or bot-service-reserved route, or carried a Teams shadow would-deny decision. Ordinary reads without a shadow decision are not recorded. This records admission, not the operation's result. |
workspace.owner_bootstrapped | Owner bootstrapped | An operator ran the Owner bootstrap command. The principal is service, the actor is operator-cli, and the target user is the new Owner. |
Actions without a friendly label are shown by their raw name.
Channel binding changes are recorded as team.binding_added (Team channel binding added) and
team.binding_removed (Team channel binding removed) for Slack channels and Linear teams. These record
routing changes, not membership grants or transfers of existing session ownership.
In shadow Teams enforcement, an Authorization allowed event can carry a shadow_denied:<reason> reason, or shadow_denied:batch with per-session details. That means the Teams resolver would have denied access but legacy admission allowed it; it is not a denied request. Private-session and team-owned non-read checks remain enforced in every mode.
Reading the log
Events are listed newest first, 25 per page. The Team selector defaults to All teams and can narrow the log to a selected team. The page has no search or export, and no retention period is stated. Use Previous and Next to move between pages; the current page number is shown between the buttons. After changing pages the list scrolls back to the heading.
When there are no events, the page shows "No audit events yet" with the note "Workspace activity will appear here as it is recorded."
If a refresh fails while events are already loaded, a banner reads "Unable to refresh the audit log. Showing the most recently loaded events." with a Retry button. If the first load fails, the page shows "Unable to load the audit log." with Retry.
Typical uses
Who changed a role. Look for Member role updated events. The Actor is the person who made the change, the Resource line names the target user, and Structured details shows the role IDs before and after.
Why a request was denied. Look for Authorization denied events. The Reason field carries the denial code; Structured details shows the HTTP method and path, plus the required and effective permissions when the denial includes them. Audit writes can fail, so absence of an event does not prove authorization succeeded.
Correlating with a support request. Ask the person for the request ID from the error they saw, then match it against the Request field. Non-request events such as default-role assignment or Owner bootstrap instead carry a synthetic request ID.
Confirming an Owner bootstrap. After an operator runs the bootstrap command, a workspace.owner_bootstrapped event with actor operator-cli appears with the new Owner as the target user.
Reviewing a team access change. Select the team, then check membership, repository-grant, and collaborator events. A private-session break-glass read is recorded separately from a visibility change, and an automation executor change does not move the automation to another team.