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.

For the account lifecycle, what deletion removes and keeps, and the backup replay design, see User deactivation and deletion.

MCP and personal access tokens​

External chat apps authenticate to /api/mcp with a personal access token. The token is bound to one organisation and every call is checked against the user's current membership, role, groups, project access, and item-level security.

danger

Personal access tokens are not limited to MCP. They carry all of the user's privileges through the full REST API, including server-admin authority when applicable. The selected organisation becomes active, but a tool catalog that omits an administrative or destructive action does not reduce what a leaked token could do through other API routes.

Use a dedicated token per client, choose a finite expiry, store secrets in the client's approved secret storage, and review last-use metadata. Revoke tokens when a device is lost, an integration is removed, or the user no longer needs it. Never put a token in a prompt, screenshot, support bundle, source file, or application log.

The external client owns its model and transcript. TOW receives MCP protocol requests and the tool arguments needed to perform requested operations; ordinary domain writes keep their normal audit and activity records. See Connect a chat app with MCP for setup details and the current PAT-header compatibility boundary.

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 and runtime settings should be configured in tow.yaml:

  • openai_base_url.
  • openai_reasoning_model.
  • openai_reasoning_effort.
  • openai_fast_model.
  • openai_title_model.
  • openai_onboarding_model.
  • openai_embedding_model.
  • max_tool_rounds.
  • 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.