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

What is sent and what is receivedEach sending and receiving channel is turned on separately. Only decision forwarding comes on with 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).

ResultHandling
SuccessDelivered
429 · 5xx · connection failureSent again with exponential backoff (from 1 second up to retry-max-backoff-ms 60000)
A 4xx other than 429DEAD_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

ChannelSettingWhen it sends or receives
Decision forwardingcontexa.saas.enabledFor each decision (except allow and pending)
Decision feedbackcontexa.saas.decision-feedback.enabledWhen an administrator releases a block
Threat outcomescontexa.saas.threat-outcome.enabledWhen an administrator releases a block
Prompt context auditcontexa.saas.prompt-context-audit.enabledWhen Layer 1 or Layer 2 builds the prompt context
Performance telemetrycontexa.saas.performance-telemetry.enabledAggregated and sent hourly
Baseline statistics · seedscontexa.saas.baseline-signal.enabledOrganization 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 signalscontexa.saas.threat-intelligence.enabledReceived hourly, cached 90 minutes
Detection strategiescontexa.saas.detection-strategy.enabledReceived 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

SettingDefaultMeaningWhen to change
contexa.saas.enabledfalseTurns the SaaS connection ontrue to send to the SaaS
contexa.saas.endpointhttps://saas.ctxa.aiThe receiving serverWhen given another endpoint
contexa.saas.pseudonymization-secretdevelopment value (refused when on)Pseudonym HMAC key (at least 32 bytes)Always when on (32 bytes or more)
contexa.saas.global-correlation-secretdevelopment value (refused when on)Global IP correlation key (at least 32 bytes)Always when on (32 bytes or more)
contexa.saas.oauth2.token-urihttps://saas.ctxa.ai/oauth2/tokenToken endpointWhen given another token endpoint
contexa.saas.oauth2.client-id / client-secretdev-client / dev-secretReplace with the issued credentialsAlways when on
contexa.saas.include-reasoningfalseAlso send the reasoning textWhen you decided to send the reasoning too
contexa.saas.max-retry-attempts10DEAD_LETTER from this many attemptsRaise it on unstable networks
contexa.saas.dispatch-interval-ms30000Retry intervalTo retry sooner or later

Every contexa.saas.* setting (64), including the paths and intervals of the other channels, is in the Settings Index.