contexa-core
Optional
Connecting Contexa SaaS (Optional)
An optional feature with which a Contexa application sends decision results and statistics to Contexa SaaS and receives threat signals, detection strategies and baseline seeds to use in decisions. It is off by default; every decision feature of Contexa works without it.
Know this first. The sending side (client) of this feature is all in the OSS, but the receiving server is not. The default target is
https://saas.ctxa.ai, run by Contexa, and you need OAuth2 client credentials issued by that service to actually send.
At a glance
contexa.saas.enabled=true.SendQueued in a database outbox first, sent asynchronously
- Decision forwardingDecisions other than allow and pending (pseudonymized)
- Decision feedback · threat outcomesWhen an administrator releases a block
- Prompt context auditHashes only, no prompt text
- Baseline statistics · performance telemetryAggregated periodically
OAuth2 client_credentials
Contexa SaaSsaas.ctxa.ai
ReceivePulled every hour, used in prompts
- Threat signalsUp to 3 matching signals are picked; the prompt text carries the best match
- Detection strategy packs
- Baseline seedsFill in when personal or organization baselines are thin
Turning it on
contexa:
saas:
enabled: true
pseudonymization-secret: ${CONTEXA_SAAS_PSEUDONYM_SECRET} # at least 32 bytes
global-correlation-secret: ${CONTEXA_SAAS_CORRELATION_SECRET} # at least 32 bytes
oauth2:
client-id: ${CONTEXA_SAAS_CLIENT_ID}
client-secret: ${CONTEXA_SAAS_CLIENT_SECRET}
- When on, the endpoint, secrets, OAuth2 settings and scopes are checked at startup; the application does not start if they are wrong. The two secrets are refused when empty, left at the development defaults, or shorter than 32 bytes.
- Decision forwarding first stores to the outbox table of the Contexa database, then sends. Without the outbox repository nothing is sent.
- A failed send never stops decision processing.
What leaves the application
- Pseudonymization: user, session and IP are replaced by tenant-scoped HMAC-SHA256 pseudonyms. For the IP a global correlation key is also made so the same IP can be linked across tenants.
- Sent as is: the request path, country and city, new-device and impossible-travel flags, Layer 1 and Layer 2 evaluations, the resource ID, user roles, prompt hashes and token counts, and so on.
- Left out by default: the reasoning text (
include-reasoning, default false) and the raw analysis data (include-raw-analysis-data, default false). The prompt context audit sends hashes only, never the prompt text.
Delivery and retries
Decision forwarding prevents duplicates by correlation ID, stores the item as pending in the outbox and sends it after the transaction ends (POST {endpoint}/api/saas/runtime/xai/decision-ingestions, Bearer token).
| Result | Handling |
|---|---|
| Success | Delivered |
| 429 · 5xx · connection failure | Sent again with exponential backoff (from 1 second up to retry-max-backoff-ms 60000) |
| A 4xx other than 429 | DEAD_LETTER (not sent again) |
Attempts reach max-retry-attempts (10) | DEAD_LETTER |
Retries run every dispatch-interval-ms (30 seconds) for outbox-batch-size (50) items, and only one server runs them in a cluster.
Turning on each channel
| Channel | Setting | When it sends or receives |
|---|---|---|
| Decision forwarding | contexa.saas.enabled | For each decision (except allow and pending) |
| Decision feedback | contexa.saas.decision-feedback.enabled | When an administrator releases a block |
| Threat outcomes | contexa.saas.threat-outcome.enabled | When an administrator releases a block |
| Prompt context audit | contexa.saas.prompt-context-audit.enabled | When Layer 1 or Layer 2 builds the prompt context |
| Performance telemetry | contexa.saas.performance-telemetry.enabled | Aggregated and sent hourly |
| Baseline statistics · seeds | contexa.saas.baseline-signal.enabled | Organization baseline distributions aggregated per week (starting Monday); each finished week is sent (not with fewer than 3 organization or 25 user baselines). Aggregation and sending run every contexa.saas.baseline-signal.publish-interval-ms, which is 1 day when you do not set it (the 7-day default shown in the Settings Index is not used for this schedule). Seeds received hourly |
| Threat signals | contexa.saas.threat-intelligence.enabled | Received hourly, cached 90 minutes |
| Detection strategies | contexa.saas.detection-strategy.enabled | Received hourly |
A limit of the current version. Receiving threat knowledge (
contexa.saas.threat-knowledge.enabled) does not pull anything even when on, because the setting is not passed to the decision engine.
Main settings
| Setting | Default | Meaning | When to change |
|---|---|---|---|
contexa.saas.enabled | false | Turns the SaaS connection on | true to send to the SaaS |
contexa.saas.endpoint | https://saas.ctxa.ai | The receiving server | When given another endpoint |
contexa.saas.pseudonymization-secret | development value (refused when on) | Pseudonym HMAC key (at least 32 bytes) | Always when on (32 bytes or more) |
contexa.saas.global-correlation-secret | development value (refused when on) | Global IP correlation key (at least 32 bytes) | Always when on (32 bytes or more) |
contexa.saas.oauth2.token-uri | https://saas.ctxa.ai/oauth2/token | Token endpoint | When given another token endpoint |
contexa.saas.oauth2.client-id / client-secret | dev-client / dev-secret | Replace with the issued credentials | Always when on |
contexa.saas.include-reasoning | false | Also send the reasoning text | When you decided to send the reasoning too |
contexa.saas.max-retry-attempts | 10 | DEAD_LETTER from this many attempts | Raise it on unstable networks |
contexa.saas.dispatch-interval-ms | 30000 | Retry interval | To retry sooner or later |
Every contexa.saas.* setting (64), including the paths and intervals of the other channels, is in the Settings Index.