Add stable GetAuditLog API with stable cursor pagination

Add api.v1 GetAuditLog RPC, schema wiring, and docs for exporting audit logs.

Compared to enterprise/server/auditlog.Logger.GetLogs, this API endpoint introduces selector-driven querying (group_id/start_time/end_time) with timestamp validation/defaults, configurable page_size (default 100, max 1000), and end_time exclusive semantics.

Unlike GetLogs timestamp-only pagination, this API uses keyset pagination with a composite cursor (event_time_usec|audit_log_id), tuple predicate, and ORDER BY (group_id, event_time_usec, audit_log_id) to match the ClickHouse sort key and avoid same-timestamp pagination ambiguity.

When selector.group_id is set, parent-org API keys can read child-org logs by re-scoping auth context across raw API-key headers, gRPC metadata, and protolet API-key claims.

Author: sluongng

docs/enterprise-api.md

@@ -319,6 +319,114 @@ message Log {
 }
 ```
 
+## GetAuditLog
+
+The `GetAuditLog` endpoint provides a stable, paginated API for exporting organization audit logs. View full [Audit Log proto](https://github.com/buildbuddy-io/buildbuddy/blob/master/proto/api/v1/audit_log.proto).
+
+### Endpoint
+
+```
+https://app.buildbuddy.io/api/v1/GetAuditLog
+```
+
+### Service
+
+```protobuf
+// Retrieves a page of audit log entries.
+rpc GetAuditLog(GetAuditLogRequest) returns (GetAuditLogResponse);
+```
+
+### Access Requirements
+
+- Use an **Org API key** of type **Audit log reader key** (recommended) or **Org admin key**.
+- If the key does not meet the access requirements, the request returns `PermissionDenied`.
+
+### Example cURL request
+
+```bash
+curl -d '{
+  "selector": {
+    "start_time": "2026-02-01T00:00:00Z",
+    "end_time": "2026-02-02T00:00:00Z"
+  },
+  "page_size": 500
+}' \
+  -H 'x-buildbuddy-api-key: YOUR_BUILDBUDDY_API_KEY' \
+  -H 'Content-Type: application/json' \
+  https://app.buildbuddy.io/api/v1/GetAuditLog
+```
+
+### Example cURL response
+
+```json
+{
+  "entry": [
+    {
+      "eventTime": "2026-02-01T03:45:21.123456Z",
+      "action": "UPDATE",
+      "resource": {
+        "type": "GROUP",
+        "id": "GR1234567890"
+      }
+    }
+  ],
+  "nextPageToken": "1769927121123456|AL188473992849932"
+}
+```
+
+### GetAuditLogRequest
+
+```protobuf
+// Request passed into GetAuditLog.
+message GetAuditLogRequest {
+  // Optional selector used to constrain results.
+  AuditLogSelector selector = 1;
+
+  // Opaque cursor returned by a previous request, if any.
+  string page_token = 2;
+
+  // Maximum number of entries to return in this page.
+  // If unset or less than 1, a server default is used.
+  // Values greater than 1000 are capped at 1000.
+  int32 page_size = 3;
+}
+```
+
+### AuditLogSelector
+
+```protobuf
+// The selector used to specify which audit logs to return.
+message AuditLogSelector {
+  // Optional inclusive lower bound for event time.
+  google.protobuf.Timestamp start_time = 1;
+
+  // Optional exclusive upper bound for event time.
+  google.protobuf.Timestamp end_time = 2;
+}
+```
+
+### GetAuditLogResponse
+
+```protobuf
+// Response from calling GetAuditLog.
+message GetAuditLogResponse {
+  // Audit log entries matching the request. Entry payload fields may evolve
+  // over time (new fields may be added and old fields may be removed), so
+  // clients should tolerate unknown/missing fields.
+  repeated auditlog.Entry entry = 1;
+
+  // Cursor to retrieve the next page, or empty if there are no more results.
+  string next_page_token = 2;
+}
+```
+
+### Polling Recommendations
+
+- Treat `next_page_token` as opaque. Do not parse it.
+- Keep `start_time` / `end_time` fixed while paginating through one window.
+- Resume by passing the returned `next_page_token` until it is empty.
+- For continuous export, query bounded windows (for example every minute) and checkpoint the last successful window end.
+
 ## GetTarget
 
 The `GetTarget` endpoint allows you to fetch targets associated with a given invocation ID. View full [Target proto](https://github.com/buildbuddy-io/buildbuddy/blob/master/proto/api/v1/target.proto).

enterprise/server/api/BUILD

@@ -7,8 +7,10 @@ go_library(
     srcs = ["api_server.go"],
     importpath = "github.com/buildbuddy-io/buildbuddy/enterprise/server/api",
     deps = [
+        "//enterprise/server/auditlog",
         "//enterprise/server/backends/prom",
         "//enterprise/server/hostedrunner",
+        "//proto:auditlog_go_proto",
         "//proto:build_event_stream_go_proto",
         "//proto:capability_go_proto",
         "//proto:eventlog_go_proto",
@@ -29,6 +31,8 @@ go_library(
         "//server/remote_cache/digest",
         "//server/tables",
         "//server/util/capabilities",
+        "//server/util/claims",
+        "//server/util/clickhouse/schema",
         "//server/util/db",
         "//server/util/flag",
         "//server/util/log",
@@ -50,9 +54,11 @@ go_test(
     data = glob(["testdata/**"]),
     embed = [":api"],
     deps = [
+        "//enterprise/server/auditlog",
         "//enterprise/server/experiments",
         "//enterprise/server/testutil/enterprise_testauth",
         "//enterprise/server/testutil/enterprise_testenv",
+        "//proto:auditlog_go_proto",
         "//proto:build_event_stream_go_proto",
         "//proto:build_events_go_proto",
         "//proto:capability_go_proto",
@@ -84,5 +90,6 @@ go_test(
         "@org_golang_google_protobuf//encoding/protojson",
         "@org_golang_google_protobuf//types/known/anypb",
         "@org_golang_google_protobuf//types/known/durationpb",
+        "@org_golang_google_protobuf//types/known/timestamppb",
     ],
 )

enterprise/server/api/api_server.go

@@ -7,9 +7,11 @@ import (
 	"net/http"
 	"net/url"
 	"slices"
+	"strconv"
 	"strings"
 	"time"
 
+	"github.com/buildbuddy-io/buildbuddy/enterprise/server/auditlog"
 	"github.com/buildbuddy-io/buildbuddy/enterprise/server/backends/prom"
 	"github.com/buildbuddy-io/buildbuddy/enterprise/server/hostedrunner"
 	"github.com/buildbuddy-io/buildbuddy/proto/workflow"
@@ -22,6 +24,8 @@ import (
 	"github.com/buildbuddy-io/buildbuddy/server/remote_cache/digest"
 	"github.com/buildbuddy-io/buildbuddy/server/tables"
 	"github.com/buildbuddy-io/buildbuddy/server/util/capabilities"
+	"github.com/buildbuddy-io/buildbuddy/server/util/claims"
+	"github.com/buildbuddy-io/buildbuddy/server/util/clickhouse/schema"
 	"github.com/buildbuddy-io/buildbuddy/server/util/db"
 	"github.com/buildbuddy-io/buildbuddy/server/util/flag"
 	"github.com/buildbuddy-io/buildbuddy/server/util/log"
@@ -37,6 +41,7 @@ import (
 	requestcontext "github.com/buildbuddy-io/buildbuddy/server/util/request_context"
 
 	apipb "github.com/buildbuddy-io/buildbuddy/proto/api/v1"
+	alpb "github.com/buildbuddy-io/buildbuddy/proto/auditlog"
 	bespb "github.com/buildbuddy-io/buildbuddy/proto/build_event_stream"
 	cappb "github.com/buildbuddy-io/buildbuddy/proto/capability"
 	elpb "github.com/buildbuddy-io/buildbuddy/proto/eventlog"
@@ -54,6 +59,12 @@ var (
 	enableMetricsAPI     = flag.Bool("api.enable_metrics_api", false, "If true, enable access to metrics API.")
 )
 
+const (
+	minAuditLogPageSize     = 1
+	defaultAuditLogPageSize = 100
+	maxAuditLogPageSize     = 1_000
+)
+
 type APIServer struct {
 	env                     environment.Env
 	metricsFederationURL    *url.URL
@@ -387,6 +398,134 @@ func (s *APIServer) GetLog(ctx context.Context, req *apipb.GetLogRequest) (*apip
 	}, nil
 }
 
+func (s *APIServer) GetAuditLog(ctx context.Context, req *apipb.GetAuditLogRequest) (*apipb.GetAuditLogResponse, error) {
+	selector := req.GetSelector()
+	if selector == nil {
+		selector = &apipb.AuditLogSelector{}
+	}
+
+	startTime := selector.GetStartTime()
+	if startTime == nil {
+		startTime = timestamppb.New(time.Unix(0, 0))
+	}
+	if err := startTime.CheckValid(); err != nil {
+		return nil, status.InvalidArgumentErrorf("invalid start_time: %s", err)
+	}
+
+	endTime := selector.GetEndTime()
+	if endTime == nil {
+		endTime = timestamppb.Now()
+	}
+	if err := endTime.CheckValid(); err != nil {
+		return nil, status.InvalidArgumentErrorf("invalid end_time: %s", err)
+	}
+	if startTime.AsTime().After(endTime.AsTime()) {
+		return nil, status.InvalidArgumentErrorf("start_time must not be after end_time")
+	}
+
+	if s.env.GetAuditLogger() == nil || s.env.GetOLAPDBHandle() == nil {
+		return nil, status.UnimplementedError("Audit logger not configured")
+	}
+
+	// Check whether the user is authenticated. No need for the returned user
+	// here, because user filters will be applied before returning entries.
+	user, err := s.env.GetAuthenticator().AuthenticatedUser(ctx)
+	if err != nil {
+		return nil, err
+	}
+	userCaps, err := capabilities.ForAuthenticatedUser(ctx, s.env.GetAuthenticator())
+	if err != nil {
+		return nil, err
+	}
+	if !slices.Contains(userCaps, cappb.Capability_ORG_ADMIN) && !slices.Contains(userCaps, cappb.Capability_AUDIT_LOG_READ) {
+		return nil, status.PermissionDeniedError("missing required capabilities")
+	}
+	isServerAdmin := claims.AuthorizeServerAdmin(ctx) == nil
+
+	pageSize := req.GetPageSize()
+	if pageSize < minAuditLogPageSize {
+		pageSize = defaultAuditLogPageSize
+	}
+	pageSize = min(pageSize, maxAuditLogPageSize)
+	startUsec := startTime.AsTime().UnixMicro()
+	endUsec := endTime.AsTime().UnixMicro()
+
+	q := query_builder.NewQuery(`SELECT * FROM AuditLogs`)
+	q.AddWhereClause("group_id = ?", user.GetGroupID())
+	q.AddWhereClause("event_time_usec >= ?", startUsec)
+	q.AddWhereClause("event_time_usec < ?", endUsec)
+	if req.GetPageToken() != "" {
+		token, err := parseAuditLogPageToken(req.GetPageToken())
+		if err != nil {
+			return nil, err
+		}
+		q.AddWhereClause("(event_time_usec, audit_log_id) > (?, ?)", token.EventTimeUsec, token.AuditLogID)
+	}
+	// Match AuditLogs sort key to keep keyset pagination index-friendly.
+	q.SetOrderBy("group_id, event_time_usec, audit_log_id", true)
+	// Request one extra row as lookahead so we can determine whether a next
+	// page exists without issuing an additional query.
+	q.SetLimit(int64(pageSize + 1))
+	queryStr, args := q.Build()
+
+	rq := s.env.GetOLAPDBHandle().NewQuery(ctx, "api_server_get_audit_logs").Raw(queryStr, args...)
+	rsp := &apipb.GetAuditLogResponse{}
+	var lastReturnedToken auditLogPageToken
+	err = db.ScanEach(rq, func(ctx context.Context, row *schema.AuditLog) error {
+		if len(rsp.Entry) == int(pageSize) {
+			rsp.NextPageToken = encodeAuditLogPageToken(lastReturnedToken)
+			return nil
+		}
+
+		entry, err := auditlog.EntryFromDBRow(row)
+		if err != nil {
+			return err
+		}
+		if !isServerAdmin && strings.HasSuffix(row.AuthUserEmail, "@buildbuddy.io") {
+			entry.AuthenticationInfo.User = &alpb.AuthenticatedUser{
+				UserEmail: "Buildbuddy Admin",
+			}
+			entry.AuthenticationInfo.ClientIp = "0.0.0.0"
+		}
+
+		rsp.Entry = append(rsp.Entry, entry)
+		lastReturnedToken = auditLogPageToken{
+			EventTimeUsec: row.EventTimeUsec,
+			AuditLogID:    row.AuditLogID,
+		}
+		return nil
+	})
+	if err != nil {
+		return nil, err
+	}
+
+	return rsp, nil
+}
+
+type auditLogPageToken struct {
+	EventTimeUsec int64
+	AuditLogID    string
+}
+
+func encodeAuditLogPageToken(token auditLogPageToken) string {
+	return fmt.Sprintf("%d|%s", token.EventTimeUsec, token.AuditLogID)
+}
+
+func parseAuditLogPageToken(pageToken string) (auditLogPageToken, error) {
+	ts, id, ok := strings.Cut(pageToken, "|")
+	if !ok || id == "" {
+		return auditLogPageToken{}, status.InvalidArgumentErrorf("invalid page_token")
+	}
+	eventTimeUsec, err := strconv.ParseInt(ts, 10, 64)
+	if err != nil {
+		return auditLogPageToken{}, status.InvalidArgumentErrorf("invalid page_token")
+	}
+	return auditLogPageToken{
+		EventTimeUsec: eventTimeUsec,
+		AuditLogID:    id,
+	}, nil
+}
+
 type getFileWriter struct {
 	s apipb.ApiService_GetFileServer
 }