# Organization administration

What an organization's owners and admins can see and change about the organization
itself, from **Settings**. Each section says who may use it, because the answer differs
and the server, not the screen, decides it.

## Audit log

**Settings › Audit log** lists this organization's audit trail, newest first: who acted,
what they did, to what, from which address, and when. Each row is written as one
sentence, the same sentence the accountability ledger uses, with the raw action name and
result beneath it.

**Who can open it:** organization **owners** only (`org:admin`). An admin, member,
viewer or billing user gets a 403, and the screen shows that refusal rather than an
empty list. A page of the log is a page of every member's IP addresses and browsers, so
it is gated the way the SIEM sinks and data-subject requests are. The machine export
below is gated more loosely, on `read`, because a script holding a member's token could
already pull it.

**Filters:**

| Filter | Matches |
| --- | --- |
| Who | A member. Also matches what an agent did **on that person's behalf**. |
| Action | An action name exactly (`team.create`), or a prefix ending in `*` (`team.*`). Any other `*`, `%` or `_` is refused, not read as a pattern. |
| Target type, Target id | The object acted on, as recorded (`project`, `team`, `org`, …). |
| From, To | Whole days in your time zone. `To` includes the whole day you pick. |
| Only actions taken by the deployment operator | See below. |

**Rows the deployment operator wrote.** When the people who run this Bucker deployment
change something in your organization from their console, two audit rows are written:
one in their own organization and one in yours, in your vocabulary
(`project.ingest.suspended`), carrying `byDeploymentOperator: true`. Those rows are
marked **By deployment operator** here. There is no impersonation: the operator's own
name is the actor.

**Not plan-gated.** The browser works on every plan, Free included, so that those
operator rows are always readable. The export is the paid feature.

**Reading it is recorded.** Every page served writes an `audit.browse` row (who, which
filters, how many rows), after the page is read, so it appears at the top of the next
one. The screen only asks for a page when you press **Apply filters** or **Load older
records**, never in the background.

**Download.** The **Audit-log export** card under the list downloads the same rows as
JSON Lines for a date range. It needs a paid plan (the `auditApi` feature).

### The API

```
GET /orgs/:orgSlug/compliance/audit-log
    ?actor=<principalId>&action=<name|prefix*>&targetType=&targetId=
    &from=<ISO>&to=<ISO, exclusive>&operator=true&cursor=&limit=<1..200, default 50>
```

Answers `{ entries: [...], nextCursor }`, newest first. `nextCursor` is null once the
filter is exhausted; pass it back as `cursor` with the same filters for the next, older
page. Each entry carries `actor` and `onBehalfOf` as `{ principalId, displayName, kind }`
(`displayName` is null when the principal no longer exists), `outcome`
(`APPROVAL` / `DECLINE` / `NEUTRAL`, the accountability ledger's classification), the
`ipAddress`, `userAgent`, `metadata` and `byDeploymentOperator`. `from` must be earlier
than `to`. A malformed cursor is a 400.

For bulk, oldest-first pulls into a SIEM, use `GET /orgs/:orgSlug/compliance/audit-log/export`
(JSON Lines) or a streaming sink instead.

### Who acted, and how: the actor fields

Every audit row records, beside the principal, the **mode**, **transport** and **credential**
of the act. The server derives them from the credential that was verified; no header, request
body or tool argument can set them.

| Field | Values |
| --- | --- |
| `actorMode` | `interactive` (a person on a session or a personal access token), `delegated_client` (an OAuth client acting for a person), `autonomous` (an agent), `system` (the platform: a worker, a scheduler, an inbound webhook, an organization CI token) |
| `transport` | `dashboard`, `api`, `cli`, `mcp`, `slack`, `hook`, `trigger`, `playbook`, `worker` |
| `credentialType` | `session`, `pat`, `org_token`, `agent_token`, `oauth`, `delegation`, `service` |
| `agentId` / `oauthClientIdentityId` | The agent, or the OAuth client identity, behind a non-human act. Exactly one is set on an `autonomous` or `delegated_client` row; neither on the others. |
| `clientId`, `traceId` | The OAuth `client_id` from the token, and the W3C trace id the caller sent. Both are correlation, not proof: the trace id is chosen by the client. |
| `intent` | What the caller *said* it was doing, up to 500 characters, scrubbed. It is **self-reported**: an injected agent writes it, so the export labels it `selfReported`/`untrusted` and an agent is served it as untrusted data. |
| `before` / `after` | The target as it was and became, when each is at most 4 KB; larger values are replaced by `beforeDigest` / `afterDigest` in `metadata`. |

A call an OAuth client makes for a person is recorded `delegated_client` with the client, and
the person is still named as the one it acted for; it is never filed as the person's own click.

### Read counts

Reads leave no audit row, so reads through the MCP server are counted instead:
`audit_read_counts` holds one row per hour, principal, client, tool and project with the number
of calls, rows returned and fields served under the untrusted-data label. It holds counts and
no content, is kept for the organization's audit window, and feeds the anomaly detectors: a
principal reading ten times its own earlier average is flagged before it writes anything.

### SIEM and export format (version 2)

Each line of the audit export and of a streaming sink carries `formatVersion: 2`. Version 2 only
**adds** fields: everything in version 1 is present and unchanged. The additions are the actor
fields above and an `ocsf` object (OCSF 1.5): class 6003 API Activity for tool calls and API
actions, 3004 Entity Management for configuration writes, and 3001 Account Change for grants,
tokens and agent lifecycle. A delegation appears as `actor.invoked_by`, and the four modes are
in every record (`unmapped.actor_mode`). Sinks keep their `X-Bucker-Signature`; `bucker-verify`
checks a signature, not a schema, and verifies exports from before and after the change.

### Owner alerts

An owner can opt in, per action, to be alerted when one of these is written: `agent.create`,
`agent.token.create`, `agent_grant.widen`, `agent.trust.promote`, `agent.anomaly.respond`,
`oauth_client.first_seen`, `oauth_client.enable`, `org.mcp_client_policy.update`,
`approval_policy.create`/`update`/`delete`, `agent_surface.enable`, `egress.host.add`,
`connection.credential.set`, `review_mode.update` and `review_mode.production_opt_in`, in
addition to the original security actions.

## Teams: the roster and team roles

**Settings › Teams › Roster** opens a team's detail: everyone on it with their team role
and the organization role it sits under, the projects the team is linked to, and the
ownership rules that name the team.

Teams decide which projects members below admin can reach, and a team has two roles:

| Team role | What it adds |
| --- | --- |
| Contributor | Reads and triages the team's projects. |
| Team admin | Manages the team (rename, members, roles) and **administers** its projects. |

**Who can change roles:** an organization owner or admin, or that team's own team admin.
A contributor cannot promote anyone, themselves included. A team admin can step down,
and the change takes effect on their next request, without signing out.

**Who can be a team admin:** a person whose organization role is Owner, Admin or Member.
A Viewer or Billing seat is refused, whether added as team admin or promoted to it:
team admin administers projects, which those roles do not allow. Raise the organization
role first, in **Members**. Agents cannot be team admins. The rule holds both ways:
lowering a team admin's organization role to Viewer or Billing makes them a contributor
on every team they administered, in the same change, and the `org.member.role_change`
audit row lists those teams (`teamAdminCappedTeamIds`). They stay on the teams. Raising
the organization role again does not restore the team role; promote them in the roster.

**Tokens:** a personal access token can only grant a team role whose permissions it
carries itself, so a token cannot create a team admin. Use a signed-in session.

Every change writes a `team.member.role_change` audit row with the role before and
after; adds and removals write `team.member.add` and `team.member.remove`.

**Owned paths** lists only rules on projects you can see yourself; a team you can read
does not show you another project's paths.

### The API

```
GET   /orgs/:orgSlug/teams/:teamSlug/members                  any org member
POST  /orgs/:orgSlug/teams/:teamSlug/members                  { userId, role? }  (role defaults to CONTRIBUTOR)
PATCH /orgs/:orgSlug/teams/:teamSlug/members/:principalId     { role: "TEAM_ADMIN" | "CONTRIBUTOR" }
GET   /orgs/:orgSlug/teams/:teamSlug/ownership                rules naming the team, on projects you can read
```
