Near real-time audit logs

Near real-time audit logs overview

Near real-time audit logs give you a continuous record of API activity against your Contentful organization. Each event describes a single Contentful Management API (CMA) request: who made it, what it addressed, and how Contentful responded.

Events are delivered in near real time to your configured storage destination, where they can be processed, analyzed, or retained using your existing tools. As with all Enterprise observability log sources, Contentful handles the delivery, while you manage storage, access, and downstream processing.

Events use the Open Cybersecurity Schema Framework (OCSF) version 1.3.0 and are emitted as API Activity events, so any SIEM that understands OCSF can ingest the feed without a custom parser.

Audit logs cover both writes and reads. Unlike the daily audit log exports, GET requests are part of the feed.

Audit logs as a log source

Audit logs are a log source within log streaming, alongside the Content Delivery API and GraphQL API sources. The storage destinations, credentials model, authentication flow, and delivery model are the ones you already use for your other Contentful logs.

Audit logs extend that setup rather than replace it. Because they are their own log source, each destination you want them delivered to is configured explicitly. This lets you route audit logs to a different bucket, container, or account than your API logs, and lets you enable or disable audit log delivery independently.

Delivery guarantees and best-effort delivery

Audit log streaming follows the same at-least-once, best-effort delivery model as every other log streaming source. See Delivery guarantees and Best-effort delivery for how that model works.

Specific to audit logs:

• Use metadata.correlation_uid as your deduplication key. It identifies the originating request, so two events carrying the same value describe the same call.
• Because delivery is best-effort, the absence of an event is not proof that the corresponding request did not happen.

Frequency and file output

Logs are sent every few minutes. The exact interval is not configurable. Each delivery cycle may produce multiple files.

Files are delivered in NDJSON format, compressed as .jsonl.gz, with one OCSF event per line. Each file follows the same structured naming convention as other log sources:

log_source=audit_logs/organization_id=<org_id>/year=YYYY/month=MM/day=DD/compacted-audit-logs-<uuid>.jsonl.gz

Example:

log_source=audit_logs/organization_id=274qvl9SkVAlToItncE81X/year=2026/month=05/day=28/compacted-audit-logs-b6afdaef-8bce-4f21-a8c2-72abfd3ba15c-166.jsonl.gz

Files are partitioned by organization and by the UTC date of the event. The log_source=audit_logs prefix keeps audit logs separate from your other log sources when they share a destination. There are no configuration options for delivery frequency, interval, batch size, or file format.

Events are targeted to reach your destination within 5 minutes of the originating request, subject to your destination’s own ingest latency.

Setting up audit log streaming

Audit logs are delivered to the same destinations as other log sources: Amazon S3, Google Cloud Storage, and Azure Blob Storage.

Prerequisites and limits

Before setting up audit log streaming, ensure you have:

• An Enterprise plan subscription.
• Organization owner or admin role in Contentful.
• A storage destination prepared. The provider setup steps for Amazon S3, Google Cloud Storage, and Azure Blob Storage are the same for audit logs, and a destination you already use for other log sources can receive audit logs as well.

Configuration limits: audit logs count as their own log source, so the standard limit applies independently. You can have a maximum of 2 audit log configurations per storage destination per organization, in addition to your Content Delivery API and GraphQL API configurations.

Static IP addresses

Contentful uses the same static egress IP addresses for audit logs as for other log sources. If your organization requires IP allowlisting, configure your firewall or network settings to include them. The addresses vary by data residency region.

For the full list, read Audit Logs: Static IP addresses.

Configure audit log streaming in Contentful

After preparing your cloud storage destination, complete the configuration in the Contentful web app.

1. Go to Organization settings → Observability.
2. Click Create new configuration.
3. Select Audit logs as the Log source.
4. Select a Storage provider: Amazon S3 Bucket, Google Cloud Storage, or Azure Blob Storage.
5. Enter a Configuration name. This is a descriptive label to identify this configuration (e.g. audit-logs-siem).
6. Click Save to begin streaming audit logs to your configured destination.

Audit logs are delivered under their own log_source=audit_logs prefix, so pointing an audit log configuration at a destination that already receives other log sources will not overwrite anything.

What happens next

• After successful configuration, your organization is enabled automatically. Events will begin arriving within 5–15 minutes.
• You can monitor delivery status in Organization settings → Observability in the Contentful web app, or use the delivery status API to check programmatically.
• Delivery operates on a best-effort basis, meaning logs are sent as quickly as possible, typically within minutes.
• If delivery fails, Contentful retries automatically and notifies organization owners and admins by email; undelivered logs are permanently discarded after 24 hours of continued failure — see Monitoring delivery below.

Audit log schema

Use the following schema to understand the structure of each audit log event. Each event represents a single CMA request and response, described using OCSF attributes.

When building parsers, expect that additional attributes may be added. Reference by attribute name instead of field position, and dispatch on class_uid rather than on file path so that any event class added in the future is additive for your parser.

Fields defined by OCSF but not listed below are not populated.

Classification fields

Actor fields

The whole actor object is omitted for requests where no identity was established. See Identifying actors.

Metadata fields

Request and response fields

Resource fields

resources holds up to three entries, in the order space, environment, entity. It is omitted for endpoints with no space context, such as organization-level and user-level endpoints, where metadata.tenant_uid still identifies your organization.

Enrichment fields

enrichments carries context that the HTTP layer alone cannot express, for the requests that produce it. See Enrichments for the payload of each enrichment type.

Example events

Entry update by an authenticated user:

1
{
2
  "activity_id": 3,
3
  "activity_name": "Update",
4
  "class_uid": 6003,
5
  "class_name": "API Activity",
6
  "category_uid": 6,
7
  "type_uid": 600303,
8
  "severity_id": 1,
9
  "status_id": 1,
10
  "time": 1779969600123,
11
  "duration": 142,
12
  "actor": {
13
    "user": {
14
      "uid": "<user id>",
15
      "type": "User",
16
      "type_id": 1,
17
      "email_addr": "jane.doe@example.com",
18
      "full_name": "Jane Doe"
19
    }
20
  },
21
  "metadata": {
22
    "version": "1.3.0",
23
    "uid": "9f1e7a4c-5b3d-4d2e-a8f1-2c6e9a1b4d3f",
24
    "correlation_uid": "7c4e2a1f-8b3d-4a9e-bc12-3456789abcde",
25
    "tenant_uid": "<org id>",
26
    "log_name": "cma-api-audit-log",
27
    "product": {
28
      "name": "Content Management API",
29
      "vendor_name": "Contentful"
30
    }
31
  },
32
  "api": {
33
    "operation": "/spaces/:space/environments/:environment/entries/:id"
34
  },
35
  "resources": [
36
    { "uid": "p4lm9x2q7rts", "type": "space" },
37
    { "uid": "master", "type": "environment" },
38
    { "uid": "3KsD6tJE6d", "type": "entity" }
39
  ],
40
  "http_request": {
41
    "uid": "7c4e2a1f-8b3d-4a9e-bc12-3456789abcde",
42
    "http_method": "PUT",
43
    "referrer": "https://app.contentful.com/spaces/p4lm9x2q7rts/entries",
44
    "user_agent": "contentful.js/10.4.2 (Node.js/v20.10.0)",
45
    "url": {
46
      "hostname": "api.contentful.com",
47
      "path": "/spaces/p4lm9x2q7rts/environments/master/entries/3KsD6tJE6d",
48
      "query_string": ""
49
    },
50
    "http_headers": [
51
      { "name": "x-contentful-user-agent", "value": "app contentful.js/10.4.2; platform Node.js/v20.10.0;" },
52
      { "name": "origin", "value": "https://app.contentful.com" },
53
      { "name": "authorization", "value": "CFPA[REDACTED]x7Qz" }
54
    ]
55
  },
56
  "http_response": {
57
    "code": 200,
58
    "length": 2048,
59
    "latency": 142,
60
    "http_headers": [
61
      { "name": "x-cache", "value": "PASS" }
62
    ]
63
  }
64
}

Organization-level request, with no space context and no identified actor:

1
{
2
  "activity_id": 2,
3
  "activity_name": "Read",
4
  "class_uid": 6003,
5
  "class_name": "API Activity",
6
  "category_uid": 6,
7
  "type_uid": 600302,
8
  "severity_id": 1,
9
  "status_id": 2,
10
  "time": 1779969604000,
11
  "duration": 11,
12
  "metadata": {
13
    "version": "1.3.0",
14
    "uid": "b3c1f6d8-2a47-4e19-9f52-7d0ab8e34c61",
15
    "correlation_uid": "5a9d2e70-14bc-42f8-8b31-6ce907f2a4d5",
16
    "tenant_uid": "<org id>",
17
    "log_name": "cma-api-audit-log",
18
    "product": {
19
      "name": "Content Management API",
20
      "vendor_name": "Contentful"
21
    }
22
  },
23
  "api": {
24
    "operation": "/organizations/:organization_id/organization_memberships"
25
  },
26
  "http_request": {
27
    "uid": "5a9d2e70-14bc-42f8-8b31-6ce907f2a4d5",
28
    "http_method": "GET",
29
    "referrer": "",
30
    "user_agent": "curl/8.7.1",
31
    "url": {
32
      "hostname": "api.contentful.com",
33
      "path": "/organizations/274qvl9SkVAlToItncE81X/organization_memberships",
34
      "query_string": "limit=100"
35
    },
36
    "http_headers": [
37
      { "name": "authorization", "value": "CFPA[REDACTED]4tRm" }
38
    ]
39
  },
40
  "http_response": {
41
    "code": 401,
42
    "http_headers": [
43
      { "name": "x-cache", "value": "PASS" }
44
    ]
45
  }
46
}

Interpreting audit log events

The following behavior is intentional and stable.

Identifying actors

Identify actors by actor.user.uid for users and actor.app_uid for apps. These are stable identifiers and the right keys for correlation, grouping, and detection rules.

The email_addr and full_name fields carry the user’s profile as it stood when the event was emitted. Because they are a point-in-time snapshot, a profile that was just changed can take a short while to come through, so events for the same user may carry differing values before converging on the current profile.

The actor object is omitted entirely for requests where no identity was established. Audit logs capture every request that reaches the Management API surface, from any client, which includes malformed requests and requests from clients you do not operate. A missing actor does not make an event invalid.

Missing values

Empty values are omitted rather than filled in. A serialized 0 means the value really was zero, never that Contentful did not capture it. Optional fields and objects such as duration, http_response.length, actor, resources, and enrichments are absent from the JSON when they do not apply.

Two request fields are exceptions and are delivered as empty strings when the client sent nothing: http_request.referrer and http_request.url.query_string.

Severity and detections

severity_id is always 1, Informational. Audit logs are an event stream, not a security signal. Build detections on status_id, activity_id, api.operation, and resource patterns, so that transport failures such as HTTP 5xx responses are not conflated with security incidents.

Unknown values use OCSF sentinels: activity_id 0 for Unknown and 99 for Other both come from the specification. Contentful does not invent enum values.

Activity IDs and content operations

activity_id reflects the HTTP method, not the content operation. Publish, unpublish, archive, schedule, and workflow transitions are usually expressed as PUT and therefore appear as activity_id 3 (Update). Some, notably unpublish, can also be expressed as DELETE, so the same logical action can arrive with a different value depending on the client.

Match on api.operation when a rule needs to detect a specific content operation.

Resource types

resources[].type is space, environment, or entity. The Management API exposes many specific object types, including entries, assets, content types, tags, releases, roles, webhooks, and API keys, and all of them appear as entity so that the schema stays stable as the API grows. Parse http_request.url.path if you need the specific type.

Enrichments

Some requests carry information that the HTTP layer alone cannot express. A bulk action names every entity it addressed in its request body, and an AI action invocation records which model produced which output. Contentful delivers that context on the same event, in the OCSF enrichments array, so there is no second event to correlate.

Two enrichment types are populated today:

• Bulk actions, type BulkActionEnrichment: the operation performed and the full set of entities it addressed, which resources does not list individually.
• AI actions, type AiActionEnrichment: the invocation, the AI action and entry involved, and the model that served it.

A request can produce more than one entry, including entries of different types. Read data.payload according to type and data.type_version. Both the set of enrichment types and the fields inside data.payload may grow over time, so ignore payload fields you do not recognize rather than rejecting the entry.

Bulk actions

data.payload is an array of action and entities pairs. action is the bulk operation, such as publish, unpublish, validate, or duplicate. entities lists the addressed items as Contentful links.

1
{
2
  "name": "resources",
3
  "value": "N/A",
4
  "type": "BulkActionEnrichment",
5
  "provider": "1f8c3a9d-52b4-4e07-9a6d-c31b8e45f207/enrichment/6d41a0b8-3e57-4c92-b8f1-2a9e07c5d431",
6
  "created_time": 1779969612480,
7
  "data": {
8
    "type_version": "1.0.0",
9
    "created_time": 1779969612480,
10
    "payload": [
11
      {
12
        "action": "validate",
13
        "entities": [
14
          { "sys": { "type": "Link", "linkType": "Entry", "id": "3KsD6tJE6d" } },
15
          { "sys": { "type": "Link", "linkType": "Entry", "id": "7fCVLCDShH" } }
16
        ]
17
      }
18
    ]
19
  }
20
}

On a bulk action request, resources identifies the space, the environment, and the bulk action itself. The entries the action addressed are in enrichments[].data.payload[].entities[].

AI actions

data.payload is an array of invocations, each recording the AI action invoked, the entry and field affected, and the model that served the request.

1
{
2
  "name": "resources",
3
  "value": "N/A",
4
  "type": "AiActionEnrichment",
5
  "provider": "8a2e5f14-7b93-4d60-a1c8-5e07b9d3f462/enrichment/c05f9b73-1d24-42a8-9e36-7f18ca40b5de",
6
  "created_time": 1779970104250,
7
  "data": {
8
    "type_version": "1.1",
9
    "created_time": 1779970104250,
10
    "payload": [
11
      {
12
        "invocationId": "5wQ2mNbT8kRfPzL3vYcH1s",
13
        "aiActionId": { "sys": { "type": "Link", "linkType": "AiAction", "id": "2pKdR7nMxQwJ4tBvZs9Lqe", "version": 5 } },
14
        "createdBy": { "sys": { "type": "Link", "linkType": "User", "id": "<user id>" } },
15
        "entryAffected": {
16
          "entityId": "3KsD6tJE6d",
17
          "entityType": "Entry",
18
          "fieldId": "productDescription",
19
          "sourceLocale": "en-US"
20
        },
21
        "modelName": "anthropic.claude-4-5-sonnet",
22
        "modelProvider": "aws_bedrock",
23
        "modelTemperature": 0.1,
24
        "outputFormat": "Suggestion"
25
      }
26
    ]
27
  }
28
}

Migrating from daily audit log exports

If your organization already consumes daily audit log exports, the near real-time feed differs in ways that require changes to your ingest pipeline. Re-validate your parsers and detection rules against the tables below.

Coverage and file format

Consuming the near real-time feed means decompressing gzip and parsing line by line, rather than parsing one JSON document per file.

Event shape

If you previously joined audit events to other logs on metadata.uid, switch that join to metadata.correlation_uid.

Actors

Near real-time audit logs use the OCSF value type_id 1 for a user, where the daily export emits 2.

Resources and enrichments

Bulk and AI action entries stay in enrichments, close to the shape you already parse. Within an entry:

So code reading enrichment.data[0].entities reads enrichment.data.payload[0].entities, code reading enrichment.created_time as a string receives an integer, and code reading enrichment.data.created_time as a string also receives an integer. Those three are the only breaking changes within an entry.

Monitoring delivery

Audit log configurations appear in Organization settings → Observability alongside your other log source configurations, and are monitored the same way. Delivery statuses, email notifications to organization owners and admins, automatic retries, and the 24-hour window before undelivered logs are discarded all behave as described in Monitoring delivery and Troubleshooting log delivery failures.

Receiving duplicate events

Duplicate events are expected. Audit log streaming uses an at-least-once delivery model by design. Use the metadata.correlation_uid field to deduplicate events in your downstream pipeline.

Logs are missing for a past time period

If audit log delivery was not enabled and configured during that period, those logs cannot be recovered. Contentful does not backfill historical audit logs.

Limitations

• resources does not list the entities a bulk operation addressed. For endpoints such as bulk actions, resources identifies the space, the environment, and the bulk action itself. The entities are in enrichments.
• api.operation can be absent. When no route pattern is resolved for a request, the api object is omitted. The rest of the event, including the concrete request path, is unaffected.

Related reading

• Enterprise observability
• Audit logs (daily export)
• OCSF API Activity class, version 1.3.0
• OCSF enrichment object, version 1.3.0