From 78db636f230f6f9d25e5cb273ef24b05fb65902c Mon Sep 17 00:00:00 2001 From: Harsh23Kashyap Date: Fri, 14 Aug 2026 02:00:46 +0530 Subject: [PATCH 1/3] docs: bring audit log docs in sync with code The action type table in docs/docs/configuration/audit-logs.mdx was missing four entries that the code actually writes (org.member_deactivated, org.member_reactivated, scim_token.created, scim_token.deleted) and had one stale entry the code never writes (user.delete). The page also did not document the four query parameters (page, perPage, since, until) or the two response headers (X-Total-Count, Link) that the public OpenAPI spec already describes. The targetType enum and metadata schema on the same page are updated to include scim_token. --- docs/docs/configuration/audit-logs.mdx | 45 ++++++++++++++++++++++---- 1 file changed, 39 insertions(+), 6 deletions(-) diff --git a/docs/docs/configuration/audit-logs.mdx b/docs/docs/configuration/audit-logs.mdx index 1db8f6a66..e178ca151 100644 --- a/docs/docs/configuration/audit-logs.mdx +++ b/docs/docs/configuration/audit-logs.mdx @@ -124,7 +124,6 @@ curl --request GET '$SOURCEBOT_URL/api/ee/audit' \ | `chat.visibility_updated` | `user` | `chat` | | `user.created_ask_chat` | `user` | `org` | | `user.creation_failed` | `user` | `user` | -| `user.delete` | `user` | `user` | | `user.fetched_file_blame` | `user` | `org` | | `user.fetched_file_source` | `user` | `org` | | `user.fetched_file_tree` | `user` | `org` | @@ -143,11 +142,44 @@ curl --request GET '$SOURCEBOT_URL/api/ee/audit' \ | `user.read` | `user` | `user` | | `user.signed_in` | `user` | `user` | | `user.signed_out` | `user` | `user` | -| `org.member_promoted_to_owner` | `user` | `user` | -| `org.owner_demoted_to_member` | `user` | `user` | | `org.member_added` | `user` | `user` | -| `org.member_removed` | `user` | `user` | +| `org.member_deactivated` | `user` | `user` | | `org.member_left` | `user` | `user` | +| `org.member_reactivated` | `user` | `user` | +| `org.member_removed` | `user` | `user` | +| `org.member_promoted_to_owner` | `user` | `user` | +| `org.owner_demoted_to_member` | `user` | `user` | +| `scim_token.created` | `user` | `scim_token` | +| `scim_token.deleted` | `user` | `scim_token` | + + +## Query parameters and response headers + +The endpoint is paginated and accepts a time range filter. + +### Query parameters + +| Parameter | Type | Default | Description | +| :------- | :------ | :------ | :------ | +| `page` | positive integer | `1` | Page number. | +| `perPage` | positive integer, max `100` | `50` | Number of records per page. | +| `since` | ISO 8601 timestamp | — | Return records at or after this timestamp (inclusive). | +| `until` | ISO 8601 timestamp | — | Return records at or before this timestamp (inclusive). | + +`since` must be strictly before `until` if both are supplied; otherwise the endpoint returns `400`. + +### Response headers + +| Header | Description | +| :------- | :------ | +| `X-Total-Count` | Total number of audit records matching the current `since` / `until` filter across all pages. | +| `Link` | Pagination links (`rel="first"`, `rel="prev"`, `rel="next"`, `rel="last"`) formatted per [RFC 8288](https://datatracker.ietf.org/doc/html/rfc8288). Only set when more than one page of results exists. | + +```bash icon="terminal" Fetch audit logs for a time range, then page +curl --request GET '$SOURCEBOT_URL/api/ee/audit?since=2026-08-01T00:00:00Z&until=2026-08-13T23:59:59Z&perPage=25' \ + --header 'X-Org-Domain: ~' \ + --header 'X-Sourcebot-Api-Key: $SOURCEBOT_OWNER_API_KEY' +``` ## Response schema @@ -194,7 +226,7 @@ curl --request GET '$SOURCEBOT_URL/api/ee/audit' \ }, "targetType": { "type": "string", - "enum": ["user", "org", "file", "api_key", "account_join_request", "invite", "chat"] + "enum": ["user", "org", "file", "api_key", "account_join_request", "invite", "chat", "scim_token"] }, "sourcebotVersion": { "type": "string" @@ -207,7 +239,8 @@ curl --request GET '$SOURCEBOT_URL/api/ee/audit' \ "message": { "type": "string" }, "api_key": { "type": "string" }, "emails": { "type": "string" }, - "source": { "type": "string" } + "source": { "type": "string" }, + "scim_token": { "type": "string" } }, "additionalProperties": false }, From 762c6c59a529e683b47cbbb9f6f7f04eb898e87c Mon Sep 17 00:00:00 2001 From: Harsh23Kashyap Date: Fri, 14 Aug 2026 02:16:50 +0530 Subject: [PATCH 2/3] docs(ee/audit): address CodeRabbit review on #1582 Three CodeRabbit findings on PR #1582, all verified against current code before fixing. - Add scim.enabled and scim.disabled rows to the action type table. They are written from a ternary at packages/web/src/ee/features/scim/actions.ts:38 (action: enabled ? 'scim.enabled' : 'scim.disabled') with target type 'org'. My initial grep for the action string missed them because the value is built, not a literal. Actor type is 'user', target type is 'org'. - Use double quotes around the URL and the API-key header in the new 'fetch with time range' curl example so SOURCEBOT_URL and SOURCEBOT_OWNER_API_KEY actually expand at shell execution. The original example on the page has the same issue but is outside this PR's diff and out of scope here. - Replace the em-dash placeholder in the since/until table cells with 'Not set' to match the rest of the docs' 'no default' convention and remove ambiguity about whether a blank cell means 'unset' or 'no default'. --- docs/docs/configuration/audit-logs.mdx | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/docs/docs/configuration/audit-logs.mdx b/docs/docs/configuration/audit-logs.mdx index e178ca151..147ee0f50 100644 --- a/docs/docs/configuration/audit-logs.mdx +++ b/docs/docs/configuration/audit-logs.mdx @@ -151,6 +151,8 @@ curl --request GET '$SOURCEBOT_URL/api/ee/audit' \ | `org.owner_demoted_to_member` | `user` | `user` | | `scim_token.created` | `user` | `scim_token` | | `scim_token.deleted` | `user` | `scim_token` | +| `scim.enabled` | `user` | `org` | +| `scim.disabled` | `user` | `org` | ## Query parameters and response headers @@ -163,8 +165,8 @@ The endpoint is paginated and accepts a time range filter. | :------- | :------ | :------ | :------ | | `page` | positive integer | `1` | Page number. | | `perPage` | positive integer, max `100` | `50` | Number of records per page. | -| `since` | ISO 8601 timestamp | — | Return records at or after this timestamp (inclusive). | -| `until` | ISO 8601 timestamp | — | Return records at or before this timestamp (inclusive). | +| `since` | ISO 8601 timestamp | Not set | Return records at or after this timestamp (inclusive). | +| `until` | ISO 8601 timestamp | Not set | Return records at or before this timestamp (inclusive). | `since` must be strictly before `until` if both are supplied; otherwise the endpoint returns `400`. @@ -176,9 +178,9 @@ The endpoint is paginated and accepts a time range filter. | `Link` | Pagination links (`rel="first"`, `rel="prev"`, `rel="next"`, `rel="last"`) formatted per [RFC 8288](https://datatracker.ietf.org/doc/html/rfc8288). Only set when more than one page of results exists. | ```bash icon="terminal" Fetch audit logs for a time range, then page -curl --request GET '$SOURCEBOT_URL/api/ee/audit?since=2026-08-01T00:00:00Z&until=2026-08-13T23:59:59Z&perPage=25' \ +curl --request GET "$SOURCEBOT_URL/api/ee/audit?since=2026-08-01T00:00:00Z&until=2026-08-13T23:59:59Z&perPage=25" \ --header 'X-Org-Domain: ~' \ - --header 'X-Sourcebot-Api-Key: $SOURCEBOT_OWNER_API_KEY' + --header "X-Sourcebot-Api-Key: $SOURCEBOT_OWNER_API_KEY" ``` From 7bc47b13559179daf855f0d5884e3d220ebb5b1a Mon Sep 17 00:00:00 2001 From: Harsh23Kashyap Date: Fri, 14 Aug 2026 10:15:35 +0530 Subject: [PATCH 3/3] docs(ee/audit): drop unused 'file' value from targetType enum MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Pre-flight review of #1582 surfaced a stale 'file' value in the targetType enum on the response schema. No createAudit call site in the codebase writes target.type='file' (verified across every await createAudit() and createAuditAction() call site in packages/ excluding tests). The seven real target.type values are: user, org, api_key, account_join_request, invite, chat, scim_token. All seven are already in the enum after this change. actorType enum still includes 'api_key' alongside 'user'. This is pre-existing in the doc (not introduced by #1582) and may be aspirational/forward-looking — no current code path writes actor.type='api_key', but the Prisma schema stores actorType as a free-form String so the value is not blocked at the database layer. Reporting only; not changing in this PR to keep the diff scoped to the #1581 issue. --- docs/docs/configuration/audit-logs.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/configuration/audit-logs.mdx b/docs/docs/configuration/audit-logs.mdx index 147ee0f50..0b8288408 100644 --- a/docs/docs/configuration/audit-logs.mdx +++ b/docs/docs/configuration/audit-logs.mdx @@ -228,7 +228,7 @@ curl --request GET "$SOURCEBOT_URL/api/ee/audit?since=2026-08-01T00:00:00Z&until }, "targetType": { "type": "string", - "enum": ["user", "org", "file", "api_key", "account_join_request", "invite", "chat", "scim_token"] + "enum": ["user", "org", "api_key", "account_join_request", "invite", "chat", "scim_token"] }, "sourcebotVersion": { "type": "string"