Cloud Portal Advanced Configuration

This guide covers advanced Cloud Portal configuration options for organization administrators. These features are available at the org-admin level and affect how the portal interacts with the Arbitex Platform API, DLP pipeline, and notification system.

1. Advanced Organization Settings

Organization settings control portal-wide behavior including timezone display, MFA enforcement, and IP-based access restrictions. All settings are managed through the portal settings page or the settings API.

Settings Overview

Setting	Field	Type	Default	Description
Organization name	`org_name`	string	—	Display name for the organization.
Contact email	`contact_email`	string	—	Primary contact email for the organization.
Timezone	`timezone`	string	`UTC`	IANA timezone string (e.g. `America/New_York`). Affects portal display times and billing period display.
Date format	`date_format`	string	`ISO 8601`	Date display format in the portal UI.
Session timeout	`session_timeout_minutes`	int	`60`	Session inactivity timeout in minutes.
MFA required	`require_mfa`	bool	`false`	Enforce multi-factor authentication for all users in the organization.
IP allowlist	`allowed_ip_ranges`	list[string]	`[]`	CIDR ranges that are allowed to access the portal.
Data residency	`data_residency_region`	string	`us`	Data residency region (read-only).

Timezone

The timezone setting uses IANA timezone format (e.g. America/New_York, Europe/London, Asia/Tokyo). This setting affects:

Portal display times — all timestamps in the portal UI are converted to the configured timezone.
Billing period display — billing cycle start/end dates are shown in the organization’s timezone.

The timezone is validated against the IANA timezone database on update. Invalid timezone strings (e.g. EST, GMT+5) are rejected with a 422 error.

MFA Enforcement

Setting require_mfa to true enforces multi-factor authentication for all users in the organization. This setting:

Takes effect on next login. Users who are currently logged in are not forced to re-authenticate, but must complete MFA on their next session.
Applies to all users regardless of role, including org admins.
Cannot be bypassed by individual user settings.

IP Allowlist

The allowed_ip_ranges field accepts a list of CIDR strings that restrict portal access to specific networks. When configured:

Only requests originating from the configured CIDR ranges can access the portal.
Each entry is validated against CIDR/IP format on save.
Lockout prevention: The portal validates that your current IP address is included in the list before saving. If your current IP would be blocked by the new configuration, the save is rejected with a 400 error to prevent self-lockout.

{
  "allowed_ip_ranges": [
    "10.0.0.0/8",
    "192.168.1.0/24",
    "203.0.113.42/32"
  ]
}

DLP Fail Mode

The DLP fail mode determines what happens when the Platform DLP service is unavailable:

Mode	Behavior	Risk
Closed (default)	Requests are blocked when DLP scanning fails. No AI traffic passes without a successful scan.	Users cannot access AI services during DLP outages.
Open	Requests are allowed through when DLP scanning fails. AI traffic passes unscanned.	Sensitive data may reach AI providers without DLP inspection.

Audit Retention

Audit retention controls how long audit events are stored before automatic cleanup:

Option	Use Case
30 days	Development and testing environments
60 days	Standard operational use
90 days	Organizations with quarterly review cycles
180 days	Compliance requirements (SOC 2, ISO 27001)
365 days	Regulatory requirements (HIPAA, financial services)

Legal hold consideration: If your organization is subject to a legal hold or litigation preservation order, audit retention should be set to the maximum (365 days) or audit data should be exported to a separate long-term storage system before the retention window closes. See Audit Log Export for export procedures.

Custom Headers

Custom headers allow you to inject additional HTTP headers into all API calls from the portal to the Arbitex Platform. This is useful for:

Routing identifiers — adding headers that load balancers or API gateways use for traffic routing.
Correlation IDs — injecting organization-specific correlation headers for cross-system tracing.
Compliance tags — adding headers required by your organization’s API governance policies.

Custom headers are configured as key-value pairs:

{
  "custom_headers": {
    "X-Org-Correlation-ID": "acme-corp-prod",
    "X-Environment": "production"
  }
}

2. DLP Policy Simulation

The DLP policy simulation feature allows administrators to test how the DLP pipeline would handle specific content without sending it through a live AI provider. This is essential for validating DLP rules before activating them, training staff on what content triggers DLP actions, and investigating past incidents.

Simulation Endpoint

POST /v1/orgs/{org_id}/policy-chain/simulate

Send sample content to the simulation endpoint to see how the current DLP policy chain would process it:

Request:

{
  "prompt": "Please process this: my SSN is 123-45-6789 and my credit card is 4111-1111-1111-1111",
  "context": {
    "provider": "openai",
    "model": "gpt-4"
  }
}

Response:

{
  "decision": "redact",
  "matched_pack": "pii-standard",
  "matched_rule": "ssn-pattern",
  "details": {
    "entity_types_found": ["SSN", "CREDIT_CARD"],
    "redacted_content": "Please process this: my SSN is [REDACTED] and my credit card is [REDACTED]",
    "confidence": 0.95,
    "scan_duration_ms": 12
  }
}

Request Fields

Field	Type	Required	Description
`prompt`	string	Yes	The content to test against the DLP policy chain. Maximum 10,000 characters.
`context`	object	No	Optional context including `provider` and `model` — some DLP rules may vary by provider or model.

Response Fields

Field	Type	Description
`decision`	string	The action the DLP pipeline would take: `allow`, `deny`, or `redact`.
`matched_pack`	string or null	The policy pack that matched, if any.
`matched_rule`	string or null	The specific rule within the pack that triggered the action.
`details`	object or null	Additional details including entity types found, redacted content, confidence score, and scan duration.

Portal Simulation Page

The portal provides a built-in simulation interface at /portal/dlp-test with:

Pre-built example prompts covering common PII patterns (SSN, credit cards, email addresses, phone numbers).
Result display showing the decision, matched rules, redacted content preview, and scan timing.
Provider/model selection to test how rules behave with different provider configurations.

Use Cases

Scenario	How to Use
Testing new DLP rules	Create the rule in draft mode, then use the simulator to verify it catches the intended patterns before activating.
Staff training	Walk team members through the simulator to demonstrate what content triggers DLP actions and how redaction looks.
Incident investigation	Reproduce a reported false positive or false negative by submitting the same content through the simulator.
Rule tuning	Adjust confidence thresholds or entity type lists, then re-test with the simulator to verify the changes produce the expected results.

3. Webhook Configuration

Webhooks deliver real-time event notifications to external systems. The portal provides tools for testing, editing, and monitoring webhook health.

Webhook Testing

Test a webhook to verify connectivity and measure latency:

POST /v1/orgs/{org_id}/webhooks/{webhook_id}/test

The test endpoint sends a synthetic event to the configured webhook URL and returns the result:

{
  "webhook_id": "wh_abc123",
  "status": "success",
  "status_code": 200,
  "response_time_ms": 145,
  "message": "Test event delivered successfully"
}

Field	Type	Description
`webhook_id`	string	The webhook identifier.
`status`	string	`success` or `failed`.
`status_code`	int or null	HTTP status code returned by the webhook endpoint. Null if the connection failed.
`response_time_ms`	int or null	Round-trip time in milliseconds. Null if the connection failed.
`message`	string	Human-readable result message.

Webhook Editing

Update an existing webhook’s configuration:

PUT /v1/orgs/{org_id}/webhooks/{webhook_id}

All webhook properties can be updated: URL, event types, secret, and enabled state. The webhook secret is used to compute the HMAC signature included in the X-Webhook-Signature header of each delivery.

Auto-Disable

Webhooks are automatically disabled after consecutive delivery failures to prevent continued attempts to unreachable endpoints. When a webhook is auto-disabled:

The webhook’s enabled field is set to false.
No further deliveries are attempted.
The portal displays a warning indicator on the webhook in the configuration list.

To re-enable an auto-disabled webhook:

Fix the underlying connectivity issue (endpoint URL, firewall rules, TLS certificate).
Use the test endpoint to verify connectivity.
Update the webhook to set enabled: true via the edit API or the portal UI.

Delivery History

Monitor webhook delivery status through the delivery history endpoints:

GET /v1/orgs/{org_id}/webhooks/deliveries
GET /v1/orgs/{org_id}/webhooks/{webhook_id}/deliveries

The first endpoint returns deliveries across all webhooks; the second filters to a specific webhook. Both include delivery status, response codes, and timing information.

Failed deliveries can be retried:

POST /v1/orgs/{org_id}/webhooks/deliveries/{delivery_id}/retry

For persistently failing deliveries, check the dead letter archive:

GET /v1/orgs/{org_id}/webhooks/dead-letters

4. Alert Threshold Tuning

Alert thresholds generate notifications when DLP scan metrics exceed configured values. Proper tuning prevents alert fatigue while ensuring anomalous activity is surfaced promptly.

Recommended Thresholds by Organization Size

Org Size	Metric	Recommended Starting Threshold
Small (<100 users)	`blocked_per_day`	50 blocks/day
Small (<100 users)	`blocked_per_hour`	10 blocks/hour
Medium (100–500 users)	`blocked_per_day`	200 blocks/day
Medium (100–500 users)	`blocked_per_hour`	50 blocks/hour
Large (500+ users)	`blocked_per_day`	500 blocks/day
Large (500+ users)	`blocked_per_hour`	100 blocks/hour

These are starting values. Every organization’s baseline is different — a team of 50 developers working on code generation will produce different DLP patterns than a team of 50 analysts using summarization.

Threshold Fatigue

Alert fatigue is the primary failure mode for threshold-based monitoring. If your team routinely ignores DLP alerts, the thresholds are too low. Follow this tuning process:

Start high. Set thresholds 2–3x above your expected daily baseline. You should receive zero or one alert per day.
Observe for one week. Monitor actual DLP scan volumes to establish a baseline.
Tune down gradually. Lower thresholds in 20% increments until you receive 1–3 alerts per week.
Investigate every alert. If you’re tempted to dismiss an alert without investigating, the threshold is too low.

Cooldown Behavior

Alert thresholds enforce a 1-hour minimum cooldown between repeated alerts for the same metric. This prevents notification storms during sustained high-volume periods.

How cooldown works:

When a threshold is exceeded, a notification is created and the threshold’s last_triggered_at timestamp is updated.
For the next 60 minutes, the same threshold will not trigger again even if the metric continues to exceed the configured value.
After 60 minutes, the threshold is eligible to trigger again on the next check cycle.
The check interval is 15 minutes — so after cooldown expires, the next alert can fire within 15 minutes.

Managing Thresholds

Thresholds are managed through the portal at /portal/alert-config or via the API:

Operation	Endpoint	Method
List thresholds	`/v1/orgs/{org_id}/alert-thresholds`	GET
Create threshold	`/v1/orgs/{org_id}/alert-thresholds`	POST
Update threshold	`/v1/orgs/{org_id}/alert-thresholds/{id}`	PATCH
Delete threshold	`/v1/orgs/{org_id}/alert-thresholds/{id}`	DELETE

Each organization can have up to 10 alert thresholds. One threshold per metric is enforced — you cannot create two thresholds for blocked_per_hour.

See Portal Notifications and DLP Alert Thresholds for the full notification system configuration and API reference.