Audit log delivery

Trebellar emits an audit log for every security-relevant action that happens on your tenant — authentication events, user-management changes, and other governance-critical operations. These logs are delivered to cloud object storage once per day so you can retain them for as long as your compliance program requires, stream them into your SIEM, or query them ad-hoc with your warehouse of choice.

This page explains:

• How the delivery pipeline works and what the files look like
• How to configure delivery (bring-your-own-bucket, or hosted on Trebellar)
• The full schema of a single audit record
• The catalog of event types Trebellar currently emits

How delivery works

Audit events are written as structured records to Trebellar’s log pipeline in real time, then batched, serialized as newline-delimited JSON (NDJSON), and delivered to the destination of your choice once every 24 hours.

Each daily file contains every audit record produced for your organization during the prior UTC day. Files are written under a deterministic key prefix so they are easy to ingest incrementally:

audit-logs/
  orgId=<your-org-id>/
    year=2026/
      month=04/
        day=19/
          trebellar-audit-2026-04-19.ndjson

Key properties of the delivery:

Configuration

There are two delivery modes. Both are configured from the Admin panel → Governance → Audit logs section of the Trebellar platform.

Option 1 — Bring your own bucket

Use this mode if you want the logs to land directly in cloud storage that you own. This is the recommended mode for regulated workloads because the data never leaves your tenancy after the handoff.

You provide:

Steps:

1. Create a dedicated bucket in your cloud provider (S3 or GCS).
2. Provision an IAM principal (IAM user for S3, service account for GCS) that has only PutObject / storage.objects.create on the target prefix. Do not grant list, read, or delete permissions — Trebellar does not need them.
3. Generate a long-lived access key and secret for that principal.
4. In Admin panel → Governance → Audit logs, choose Bring your own bucket and paste the values above.
5. Click Test connection. Trebellar will write a small .trebellar-healthcheck object and delete it. If the test succeeds, delivery starts on the next daily cycle.

Locking the bucket to Trebellar’s IP ranges

If your security policy requires bucket access to be pinned to a known set of source IPs, Trebellar publishes a stable list of egress addresses used by the audit-log delivery workers. You can attach these to your bucket policy (aws:SourceIp on S3 or a VPC Service Controls perimeter on GCS) so that writes are only accepted from Trebellar’s infrastructure.

To avoid drift between these docs and the live set, we don’t publish the ranges inline. To request the current list:

1. Contact your Customer Success representative, or email support@trebellar.com.
2. Specify the cloud provider (AWS or GCP) and the region your bucket lives in — we’ll send back the narrowest range that covers delivery to that region.
3. Trebellar announces changes to the egress set at least 30 days in advance in the changelog. Subscribe to the changelog to be notified before you need to update your bucket policy.

Option 2 — Use the Trebellar bucket

If you don’t need the logs to land in your own cloud, Trebellar can host them in a tenant-isolated bucket managed on your behalf. You’ll be issued a short-lived, read-only pre-signed URL (refreshed every 7 days) that you can use to pull the files into your SIEM or warehouse.

Steps:

1. In Admin panel → Governance → Audit logs, choose Use Trebellar bucket.
2. Pick a retention window (30, 90, 180, or 365 days).
3. Save. The admin panel will display a Download URL and a Manifest URL that you can poll for the list of available files.

Record schema

Every line of the NDJSON file is a single JSON object with the fields below. The shape is stable — Trebellar will only add new optional fields under audit_event.*, and each change is announced in the changelog with at least 30 days notice.

Top-level fields

audit_event fields

The audit_event object is the authoritative payload for downstream consumers. The top-level fields above are derived from it and kept for ergonomic querying.

Trace correlation

Each record also carries Google Cloud Logging trace fields (logging.googleapis.com/trace, logging.googleapis.com/spanId, logging.googleapis.com/trace_sampled) and a logging.googleapis.com/labels map for fast filtering. These are safe to ignore if you don’t use Cloud Logging — they never contain tenant data beyond what’s already in audit_event.

Authentication types

audit_event.authentication.type describes how the actor proved their identity to Trebellar. The current set of values:

Event catalog

The sections below enumerate every event Trebellar currently emits. The list will grow over time — new events are appended rather than repurposing existing ones, so existing consumers never break.

authentication service

Events about how users sign in and manage their credentials.

users service

Events about user-account lifecycle, scoped to the acting admin’s organization.

Sample records

A successful SAML login:

1
{
2
  "severity": "NOTICE",
3
  "message": "audit.authentication.login.success",
4
  "event_type": "audit",
5
  "service_name": "authentication",
6
  "action_name": "login",
7
  "outcome": "SUCCESS",
8
  "org_id": "org_01HF2Z8X5N",
9
  "request_id": "req_01HQW9K2B4",
10
  "httpRequest": {
11
    "requestMethod": "POST",
12
    "requestUrl": "/saml/callback",
13
    "remoteIp": "203.0.113.42",
14
    "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 14_3) AppleWebKit/537.36",
15
    "status": 302
16
  },
17
  "audit_event": {
18
    "version": "1.0",
19
    "auditLevel": "ORG_LEVEL",
20
    "deployEnvironment": "production",
21
    "eventTime": "2026-04-19T14:22:07.418Z",
22
    "orgId": "org_01HF2Z8X5N",
23
    "sourceIPAddress": "203.0.113.42",
24
    "sessionId": "sess_01HQW9K2B4",
25
    "requestId": "req_01HQW9K2B4",
26
    "request": { "method": "POST", "route": "/saml/callback" },
27
    "userIdentity": {
28
      "type": "user",
29
      "id": 4219,
30
      "email": "alex@acme.example",
31
      "name": "Alex Doe",
32
      "orgId": "org_01HF2Z8X5N",
33
      "role": "admin"
34
    },
35
    "serviceName": "authentication",
36
    "actionName": "login",
37
    "target": {
38
      "type": "user",
39
      "id": 4219,
40
      "email": "alex@acme.example",
41
      "orgId": "org_01HF2Z8X5N"
42
    },
43
    "authentication": { "type": "saml", "provider": "saml" },
44
    "response": { "statusCode": 302, "errorMessage": null, "result": "SUCCESS" }
45
  }
46
}

A denied password-reset (CSRF mismatch):

1
{
2
  "severity": "WARNING",
3
  "message": "audit.authentication.resetPassword.denied",
4
  "event_type": "audit",
5
  "service_name": "authentication",
6
  "action_name": "resetPassword",
7
  "outcome": "DENIED",
8
  "request_id": "req_01HQWB3TX0",
9
  "httpRequest": {
10
    "requestMethod": "POST",
11
    "requestUrl": "/reset-password",
12
    "remoteIp": "198.51.100.7",
13
    "status": 403
14
  },
15
  "audit_event": {
16
    "version": "1.0",
17
    "auditLevel": "APPLICATION_LEVEL",
18
    "deployEnvironment": "production",
19
    "eventTime": "2026-04-19T14:25:11.902Z",
20
    "requestId": "req_01HQWB3TX0",
21
    "request": { "method": "POST", "route": "/reset-password" },
22
    "serviceName": "authentication",
23
    "actionName": "resetPassword",
24
    "authentication": { "type": "password_reset" },
25
    "response": { "statusCode": 403, "errorMessage": "csrf_mismatch", "result": "DENIED" }
26
  }
27
}

A user-create event:

1
{
2
  "severity": "NOTICE",
3
  "message": "audit.users.createUser.success",
4
  "event_type": "audit",
5
  "service_name": "users",
6
  "action_name": "createUser",
7
  "outcome": "SUCCESS",
8
  "org_id": "org_01HF2Z8X5N",
9
  "request_id": "req_01HQWC5JPZ",
10
  "httpRequest": {
11
    "requestMethod": "POST",
12
    "requestUrl": "/api/users",
13
    "status": 200
14
  },
15
  "audit_event": {
16
    "version": "1.0",
17
    "auditLevel": "ORG_LEVEL",
18
    "deployEnvironment": "production",
19
    "eventTime": "2026-04-19T15:02:44.311Z",
20
    "orgId": "org_01HF2Z8X5N",
21
    "requestId": "req_01HQWC5JPZ",
22
    "request": { "method": "POST", "route": "/api/users" },
23
    "userIdentity": {
24
      "type": "user",
25
      "id": 4219,
26
      "email": "alex@acme.example",
27
      "orgId": "org_01HF2Z8X5N",
28
      "role": "admin"
29
    },
30
    "serviceName": "users",
31
    "actionName": "createUser",
32
    "target": {
33
      "type": "user",
34
      "id": 5502,
35
      "email": "jamie@acme.example",
36
      "name": "Jamie Lee",
37
      "orgId": "org_01HF2Z8X5N"
38
    },
39
    "requestParams": {
40
      "role": "member",
41
      "authMethod": "saml",
42
      "signupEmail": true
43
    },
44
    "response": { "statusCode": 200, "errorMessage": null, "result": "created" }
45
  }
46
}

Querying the logs

Because each file is plain NDJSON, any tool that can read line-delimited JSON works out of the box.

Pull the last hour of failed logins with jq:

$
cat trebellar-audit-2026-04-19.ndjson \
>
  | jq -c 'select(.service_name == "authentication"
>
                 and .action_name == "login"
>
                 and .outcome == "FAILURE")'

Create an external table in BigQuery:

1
CREATE OR REPLACE EXTERNAL TABLE audit.trebellar_events
2
OPTIONS (
3
  format = 'NEWLINE_DELIMITED_JSON',
4
  uris = ['gs://acme-trebellar-audit-logs/audit-logs/*/*.ndjson']
5
);

Troubleshooting