OEM Integration Guide

This guide is for a partner embedding RootTrace as an on-prem, white-labeled component of a larger product. It covers branding, programmatic access for the partner's own services, user provisioning, feeding the RootTrace audit trail into the partner's SIEM, disabling all vendor telemetry, and the support escalation model.

Everything here works on a fully on-prem install with no outbound connectivity. For the air-gapped install procedure itself, see air-gap-install.md.

1. White-label / branding

RootTrace separates deployment-wide product identity (set by the partner operator, applies to every workspace) from per-workspace login branding (set per end-customer organization).

1.1 Deployment-wide product identity

These settings rename the product across the UI, outbound email, and the SIEM export/syslog app-name. Set them once for the whole install (environment variables, shown with their setting names):

product_name and support_email are merged into every outbound email context by roottrace_email (templates do not hardcode "RootTrace"), so renaming the product also renames it in notification mail with no template edits.

For a full OEM white-label, set at minimum:

ROOTTRACE_PRODUCT_NAME="Partner Insight"
ROOTTRACE_VENDOR_MARKETING_ENABLED=false
ROOTTRACE_SUPPORT_EMAIL="soc-support@partner.example"
ROOTTRACE_TERMS_URL="https://partner.example/legal/terms"
ROOTTRACE_PRIVACY_URL="https://partner.example/legal/privacy"

1.2 Per-workspace login branding payload

Each end-customer workspace can carry its own login/app branding, edited via the workspace login settings API:

• GET /api/organizations/{organization_id}/login-settings: read current nickname + branding.
• PATCH /api/organizations/{organization_id}/login-settings: update nickname and/or the branding payload.
• POST /api/organizations/{organization_id}/login-settings/nickname-check: check vanity nickname availability.

The stored branding payload is display-only (it holds no secrets) and has the shape:

{
  "company_name": "Acme Corp",
  "logo_url": "https://.../logo.svg",
  "background_url": "https://.../login-bg.jpg",
  "app_background_url": "https://.../app-bg.jpg",
  "app_background_style": "cover",
  "colors": { "accent": "#5b8def", "...": "..." }
}

colors is a slot map; a null value for a slot clears it and falls back to the default palette. Setting company_name to an empty string clears it.

The public, pre-auth login branding lookup (/api/auth/login-branding) is an unauthenticated endpoint by design so the branded login screen can render before sign-in; it returns branding only, no tenant data.

For branding assets inside an air-gap, host them behind the partner's reverse proxy and point the *_url fields there. RootTrace stores URLs, not blobs.

2. SSO passthrough and service-account API access

The partner platform typically authenticates the end user itself, then needs to call RootTrace on that user's behalf or as a background service. Two mechanisms:

2.1 Interactive users (SSO passthrough)

End-user identity flows through the standard workspace login (vanity nickname + SSO). Provisioning of those users is handled by SCIM (section 3) so the partner's IdP remains the source of truth. RootTrace issues its own database-backed, asymmetrically signed JWTs for the browser session; the default is post-quantum ML-DSA-65, while current validated-provider FIPS deployments require RS256 or ES256. The partner does not mint RootTrace JWTs directly.

When the workspace's login mode is sso_required, the SSO mandate is enforced per workspace, not just at sign-in: RootTrace JWTs carry an RFC 8176 amr claim recording the authentication method (federated for OIDC/SAML/LDAP sign-ins), and every org-scoped request re-checks it. A session that was not established through the workspace's IdP receives 403 on that workspace even if the same account holds password access to another workspace. Service-account tokens are machine credentials and are exempt from the SSO mandate; their reach is bounded by their scopes (section 2.2).

2.2 Service accounts (/api/service-accounts)

For server-to-server calls (the partner's backend querying RootTrace, running exports, driving SCIM), create an org-scoped service account. Unlike a collector token (telemetry-ingest, single environment), a service-account token is org-scoped and carries an explicit capability scope set.

Endpoints:

• POST /api/service-accounts: create. Body: { "name": "...", "scopes": [...], "expires_in_days": <int|null> }.
• GET /api/service-accounts: list (metadata only; the token itself is returned once, at creation).
• POST /api/service-accounts/{service_account_id}/revoke: revoke.

Scopes are whitelisted, so an unknown scope is a 422, never a silently dead scope:

expires_in_days of 0 or omitted mints a non-expiring token; any positive value sets a hard expiry. The plaintext token is shown once at creation and stored only as an HMAC hash. The database never holds the token itself, so a lost token must be revoked and reissued.

Present the token as a bearer credential; the resolved identity is {organization_id, scopes, service_account_id}.

3. SCIM provisioning (/scim/v2)

RootTrace exposes SCIM 2.0 so the partner's IdP (or the partner's own user directory) provisions and deprovisions RootTrace users and groups automatically.

• Base: /scim/v2 (content type application/scim+json).
• Resources: /scim/v2/Users/{id}, /scim/v2/Groups/{id}.
• Authenticate with a service-account token that includes the scim scope (section 2.2).

Point the partner IdP's SCIM connector at https://<roottrace-host>/scim/v2 with that bearer token. Deprovisioning through SCIM is the supported way to guarantee that an offboarded end user loses RootTrace access without a manual step.

4. Audit export into the partner's SIEM

RootTrace maintains a tamper-evident audit chain and can push it into the partner's SIEM two ways. Both honor the same organization scoping: the export returns only the caller's organization audit events (STIG SRG-APP-000118).

4.1 Streaming syslog / CEF forwarding

Enable near-real-time forwarding of each audit event to an external syslog collector (RFC 5424; ArcSight-friendly). Settings:

The syslog app-name is taken from product_name, so white-labeling also renames the SIEM source. Keep audit_hash_chain_enabled=true so the audit trail is tamper-evident at rest independent of what the SIEM receives.

4.2 Pull export (/api/audit/export)

GET /api/audit/export streams the caller's organization audit events on demand:

• format: ndjson (default; one JSON object per line) or cef (ArcSight CEF lines).
• organization_id, target_id, action, search: filters.
• limit: 1–100000 (default 10000).

Use cef to drop straight into an ArcSight/CEF-consuming SIEM; use ndjson for Splunk/Elastic ingestion. Because the export exposes peers' IPs, emails, and role history, it is restricted to organization admins.

5. Telemetry kill-switch checklist

For an OEM/air-gapped deployment, confirm every outbound path is off. RootTrace already defaults these to the no-call-home posture when the deployment mode is on_prem, but verify explicitly:

• [ ] vendor_marketing_enabled=false: no vendor marketing/upsell surfaces.
• [ ] embedding_offline=true (ROOTTRACE_EMBEDDING_OFFLINE): use the model baked into the on-prem image with no runtime download. Leave ROOTTRACE_EMBEDDING_MODEL_PATH unset unless the site deliberately mounts and tests a replacement model.
• [ ] on_prem_email_relay_enabled=false (default). If email is needed, set ROOTTRACE_EMAIL_SENDING_ENABLED=true and point SMTP at the customer's own relay, so there is no call-home to the cloud email service.
• [ ] llm_provider set to a self-hosted/disabled value, or claude_base_url pointed at the partner's in-network gateway, so there is no direct Anthropic egress.
• [ ] elasticsearch_host points only inside the network (default "" = no external ES).
• [ ] ROOTTRACE_API_URL on every collector and SDK points at the partner's own deployment. The collector has no default destination and stops without this, but SDK configuration is the integrator's to set.
• [ ] Egress verified from the host itself: see Prove no egress.

6. Support model (L1 / L2 / L3)

This is how the tiers are meant to divide, not an entitlement. Whether vendor L3 is available, what it covers, and any response targets are set by the partner's support agreement, and none is implied by this guide. ByteAffinity holds no support relationship with the partner's end customers.

The end customer never contacts the vendor directly. All L3 escalations flow partner-L2 → vendor, so the white-label relationship and the air-gap boundary are preserved. For an air-gapped site, L2 collects the offline diagnostic bundle and relevant audit export excerpts before opening an L3 case, since the vendor has no network path into the customer environment.