@wildo-ai/saas-technical-doc 1.1.5 → 1.1.7

package/dist/esm/content/application-consumer-documentation-content.techdoc.js

@@ -1593,11 +1593,13 @@ not rotate secret material or repair an ownerless key.
 
 ## Close the change with evidence
 
-{{CONSUMER_FACT:source:consumer-fact:access-api-keys#usageStatisticsLimitationMarkdown}}
+{{CONSUMER_FACT:source:consumer-fact:access-api-keys#usageStatisticsMarkdown}}
 
-Until per-key tracking exists, prove deployment and retirement from controlled
-requests, application audit evidence and the workload's own secret-access and
-execution logs. A page of zero counters is not a safe deletion decision.
+After a rotation, the new key should show accepted requests and a recent
+last-accepted time, and the key it replaced should stop being accepted. The
+counters cover a rolling week, so a key a workload uses less often than weekly
+can show none: read its last-accepted time before calling it unused, and confirm
+with the owning workload before deleting a key that time does not settle.
 
 Retain a non-secret lifecycle record containing:
 
@@ -1647,11 +1649,14 @@ flowchart TD
 The non-secret prefix helps identify the credential record; it cannot prove
 that the workload received the current complete secret.
 
-{{CONSUMER_FACT:source:consumer-fact:access-api-keys#usageStatisticsLimitationMarkdown}}
+{{CONSUMER_FACT:source:consumer-fact:access-api-keys#usageStatisticsMarkdown}}
 
-Do not diagnose an apparently unused key from those counters. Correlate the
-workload's execution logs, secret-access logs, application audit trail and one
-controlled request instead.
+Only requests the application ACCEPTED the key for are counted. A key sent with
+the wrong secret, past its expiry or after deactivation is refused and leaves no
+count, and neither does a request stopped before it reaches the application. So
+a key with no recent use points at the workload not sending it; failures on a
+key with recent use point at the request itself (its scope, roles or payload).
+Confirm either reading with one controlled request.
 
 The request must carry the complete opaque value in this maintained header
 shape:
@@ -2194,7 +2199,7 @@ The maintained registered-client lifecycle is:
 
 {{CONSUMER_FACT:source:consumer-fact:access-oauth-clients#lifecycleMarkdown}}
 
-{{CONSUMER_FACT:source:consumer-fact:access-oauth-clients#currentUsageEvidenceMarkdown}}
+{{CONSUMER_FACT:source:consumer-fact:access-oauth-clients#usageEvidenceMarkdown}}
 
 ## Change the correct lifecycle layer
 
@@ -4936,7 +4941,8 @@ parser, transformation, index or detection rule accepted the event.
 | One HTTPS request containing one JSON object, with a static header or HMAC credential | Test direct delivery | This matches the current structured-JSON worker closely |
 | A provider-specific wrapper around the event | Use a narrow relay unless the exact endpoint accepts the native envelope | The relay owns the wrapper while preserving source identifiers |
 | Short-lived OAuth access tokens or managed identity | Use a provider-side relay | Token acquisition and refresh do not belong in a static credential field |
-| A JSON array or provider batch protocol | Use a relay that batches deliberately | Current delivery is one event per request; configured batch fields are reserved |
+| A plain JSON array of events | Test direct delivery with \`batchSize\` above 1 | A batch of \`json_structured\` or \`ocsf\` events is sent as one JSON array |
+| A provider-specific batch protocol | Use a relay that batches deliberately | Batching sends a plain array or one line per event, never a provider wrapper |
 | A syslog, agent, queue or private-network input | Use an adapter or relay inside that boundary | The application sends outbound HTTPS webhooks, not those transports |
 | CEF, LEEF or OCSF ingestion | Test actual emitted samples with the receiver | A format name does not prove field mapping, escaping, severity or class compatibility |
 
@@ -4994,14 +5000,23 @@ application path you operate.
 
 {{CONSUMER_FACT:source:consumer-fact:organization-siem-export#deliveryValuesMarkdown}}
 
-The current worker posts **one event per HTTP request**, and there is no setting
-that changes that — size a receiver, load balancer or billing estimate on one
-request per event.
+With the default \`batchSize\` of 1, each event is its own HTTP request. Set
+\`batchSize\` above 1 and this destination's events wait, then travel together:
+a batch is sent as soon as \`batchSize\` events are waiting, or when the oldest has
+waited \`batchWindowSeconds\`. A batch is one request body, framed the way its format
+frames several records:
 
-Two configuration fields used to sit here promising otherwise — \`batchSize\` and
-\`batchWindowSeconds\` — each accepted, stored and read by nothing. They were
-removed rather than documented as reserved: a stored number that does not change
-behaviour is worse than its absence, because a receiver sized on it is sized wrong.
+| Format | Body of a batch |
+| --- | --- |
+| \`json_structured\`, \`ocsf\` | A JSON array of the events |
+| \`cef\`, \`leef\` | One line per event, separated by newlines |
+
+A batch that holds one event is sent exactly like a single event, with no array and
+no trailing newline, so a receiver written for one event per request keeps working
+until you raise \`batchSize\`. If the receiver answers \`413 Payload Too Large\`, the
+batch is halved and sent again until the receiver accepts it; the events left out
+go in the next request. Size a receiver, load balancer or billing estimate on the
+batch size you choose.
 
 ## Limit what an exported event carries
 
@@ -5210,7 +5225,7 @@ Recommended application settings:
 | Destination | Relay HTTPS URL dedicated to the organization/environment |
 | Authentication | \`hmac_sha256\` or a dedicated \`api_key_header\` |
 | Format | \`json_structured\` |
-| Delivery | One event per request; choose timeout/retry values below the relay’s bounded acknowledgement time |
+| Delivery | \`batchSize\` 1 (one event per request) unless the relay accepts a JSON array; choose timeout/retry values below the relay’s bounded acknowledgement time |
 
 If a controlled test proves direct HEC compatibility, configure:
 
@@ -5262,9 +5277,9 @@ this guide defines the application envelope that must be conserved.`,
 Microsoft Sentinel commonly receives custom data through the Azure Monitor Logs
 Ingestion API. That API requires a Data Collection Rule (DCR), a matching JSON
 schema and Microsoft Entra OAuth authorization. The application’s SIEM exporter
-uses a static outbound credential and posts one JSON object per event; it does
-not acquire or refresh Azure OAuth tokens and does not wrap events as the JSON
-array expected by Logs Ingestion. **Use an Azure-hosted relay rather than pointing
+uses a static outbound credential and posts one JSON object per event, or a plain
+JSON array when \`batchSize\` is above 1; it does not acquire or refresh Azure OAuth
+tokens and does not shape events to the Data Collection Rule's schema. **Use an Azure-hosted relay rather than pointing
 the application directly at the Logs Ingestion API.**
 
 {{CONSUMER_FACT:source:consumer-fact:organization-siem-export#markdown}}
@@ -5458,8 +5473,8 @@ cause uncontrolled field growth.
    the document is absent.
 6. Return a temporary 503, restore the endpoint and prove dead-letter recovery
    without an unintended duplicate detection.
-7. Record receiver capacity for **one request per selected event**; application
-   batching fields are currently reserved and do not reduce that rate.
+7. Record receiver capacity for the request rate you configure: **one request per
+   selected event** at the default \`batchSize\` of 1, or one per batch above it.
 
 ## Elastic documentation to keep with the runbook
 
@@ -7285,7 +7300,7 @@ A concrete request and its response, using the members of your own organization:
 
 ~~~bash
 curl --fail-with-body \\
-  --url "$BASE_URL/api/v1/organizations/$ORGANIZATION_ID/organization-members?page=1&limit=20&sort=joinedAt:desc" \\
+  --url "$BASE_URL/api/v1/organizations/$ORGANIZATION_ID/organization-members?page=1&limit=20&sort=createdAt:desc" \\
   --header "Authorization: $ORGANIZATION_API_KEY" \\
   --header "accept: application/json"
 ~~~
@@ -7391,7 +7406,7 @@ Now list the organization's members. This exercises the collection envelope you
 
 ~~~bash
 curl --fail-with-body \\
-  --url "$BASE_URL/api/v1/organizations/$ORGANIZATION_ID/organization-members?limit=5&sort=joinedAt:desc" \\
+  --url "$BASE_URL/api/v1/organizations/$ORGANIZATION_ID/organization-members?limit=5&sort=createdAt:desc" \\
   --header "Authorization: $ORGANIZATION_API_KEY" \\
   --header "accept: application/json"
 ~~~
@@ -7456,7 +7471,7 @@ An empty \`data\` array on page 1 is a valid answer. Confirm the organization an
 page=1
 while : ; do
   response=$(curl --fail-with-body --silent \\
-    --url "$BASE_URL/api/v1/organizations/$ORGANIZATION_ID/organization-members?page=$page&limit=100&sort=joinedAt:asc" \\
+    --url "$BASE_URL/api/v1/organizations/$ORGANIZATION_ID/organization-members?page=$page&limit=100&sort=createdAt:asc" \\
     --header "Authorization: $ORGANIZATION_API_KEY" \\
     --header "accept: application/json")
   echo "$response" | jq -c '.data[]' >> members.ndjson
@@ -7468,7 +7483,7 @@ done
 
 Three rules keep a scan correct:
 
-1. **Sort by a field the reference lists as sortable, or a stable timestamp** such as \`joinedAt:asc\` for members, when you walk more than one page. A sort field the operation does not accept is ignored, not refused, and the default order applies; sorting by a field that changes during the scan (a status, a name being edited) can move a record between pages and make you skip or repeat it.
+1. **Sort by a field the reference lists as sortable, or a stable timestamp** such as \`createdAt:asc\` for members (when the membership was created), when you walk more than one page. A sort field the operation does not accept is ignored, not refused, and the default order applies; sorting by a field that changes during the scan (a status, a name being edited) can move a record between pages and make you skip or repeat it.
 2. **Stop on \`totalPages\`**, not on a short page. The last page is short by definition; an earlier page is short only when records were deleted while you scanned.
 3. **Process each record idempotently** and key your own records on \`_id\`. If the scan is interrupted, resume from the last page whose work you completed; repeating a page is safe when processing is idempotent, skipping one never is.
 
@@ -7478,7 +7493,7 @@ Search operations (\`…/search\`) add \`q\` for free text. Combine it with filt
 
 ~~~bash
 curl --fail-with-body \\
-  --url "$BASE_URL/api/v1/organizations/$ORGANIZATION_ID/organization-members/search?q=morgan&status=ACTIVE&sort=joinedAt:desc" \\
+  --url "$BASE_URL/api/v1/organizations/$ORGANIZATION_ID/organization-members/search?q=morgan&status=ACTIVE&sort=createdAt:desc" \\
   --header "Authorization: $ORGANIZATION_API_KEY" \\
   --header "accept: application/json"
 ~~~