Skip to main content

Security and AI data controls

TOW is designed as a private, single-tenant workspace. Security depends on correct deployment configuration, disciplined access management, and clear handling of AI-connected data.

Session and secret controls​

The backend signs session cookies and OIDC state with APP_SECRET.

warning

Set APP_SECRET to a long random value from your approved secrets manager before first boot. The default placeholder is rejected at startup. Changing APP_SECRET later invalidates existing sessions because old cookies can no longer be verified.

For HTTPS deployments:

  • Set session_cookie_secure: true in tow.yaml.
  • Keep session_cookie_name stable unless intentionally forcing a new cookie namespace.
  • Set session_max_age_seconds to match your session policy.
  • Store .env and platform secrets outside source control.

The app sets session cookies as HTTP-only and same-site lax. Users should still access the app only over trusted HTTPS origins in production.

Access model​

Access is enforced through:

  • Server admin status for deployment settings.
  • Organisation owner and admin roles for organisation administration.
  • Project visibility and project grants for project-scoped work.
  • Organisation, group, user, and project scopes for shared knowledge records.

Review the Permissions reference before using restricted projects for sensitive work.

warning

Restricted projects protect project-scoped access, but they are not a substitute for tenant isolation. Keep highly sensitive customers, subsidiaries, or regulated datasets in separate deployments if policy requires hard isolation.

Uploads and exports​

Uploads are stored on the backend filesystem and governed by attachment permissions. Exports download JSON to the user's device and can include sensitive operational records.

Apply the same controls to uploads and exports that you apply to confidential internal documents:

  • Back up uploads with the database.
  • Restrict production shell and volume access.
  • Avoid sending exports through unmanaged channels.
  • Remove exports from local devices after the approved use is complete.

OpenAI data controls​

The backend uses the OpenAI Responses API for reasoning and the embeddings API for semantic search.

OpenAI Responses API calls are centralized in the backend OpenAI client and set:

store=false

The backend does not use OpenAI Conversations, Assistants, Threads, or Vector Stores as hosted application memory. TOW memory, docs, tickets, decisions, risks, and snapshots remain in the deployment database and configured storage.

Embeddings are used for semantic search. The embedding model is configured by openai_embedding_model, and the embedding dimension is infrastructure-sensitive.

Optional Exa web tools​

EXA_API_KEY enables optional web search and web scrape tools used by AI workflows that need current external information. If EXA_API_KEY is not configured, those web tools are unavailable and return a configuration error to the tool layer.

Use Exa only when your organisation permits external web search in AI workflows. Search queries and fetched page content may include business context supplied by the user or assistant.

Model and provider configuration​

AI model settings should be configured in tow.yaml:

  • openai_base_url.
  • openai_reasoning_model.
  • openai_reasoning_effort.
  • openai_fast_model.
  • openai_embedding_model.
  • embedding_dim.

Environment variables can override YAML as an escape hatch, but YAML is the preferred source for non-secret model configuration. embedding_dim should be treated as read-only after data has been embedded unless you plan a vector migration and re-embedding process.

Enterprise operating practices​

Recommended controls:

  • Manage .env through a secrets manager or encrypted deployment secret store.
  • Limit server admin assignment.
  • Review organisation admins and project grants on a regular schedule.
  • Use restricted projects for sensitive project work.
  • Keep proxy, database, and volume backups under the same security classification as production data.
  • Document which external AI and web providers are approved for your deployment.