Architecture

Security Model

How UnderOcean protects your data, tenants, and AI workloads.

Authentication & sessions

  • Every request is authenticated with short-lived, cryptographically signed session tokens.
  • Sessions renew automatically on a rolling basis and expire quickly when unused, limiting the exposure window if a token is ever compromised.
  • In the browser, session tokens are never reachable by page scripts: the web app keeps them in HttpOnly, SameSite=Strict (and Secure over HTTPS) cookies and attaches them to API calls on the server side, following the OWASP ASVS session-management requirements and the IETF backend-for-frontend (BFF) recommendation. Even a cross-site scripting flaw cannot read or exfiltrate a token.
  • Cross-site request forgery is blocked in two layers: SameSite=Strict cookies and a server-side check that state-changing requests come from the app's own origin.

Role-based access control (RBAC)

Access is governed by a small set of built-in roles, enforced consistently across every part of the platform:

RoleScopeCapabilities
Platform AdminPlatformManage all organizations
Organization AdminOrganizationManage members and all projects in the organization
Organization MemberOrganizationAccess only the projects they're assigned to

Custom roles

Organizations can also define custom roles with a precise, named subset of permissions — useful when the built-in owner/admin/member/viewer roles don't map cleanly to your internal structure. See Organizations & Projects.

Role management cannot be used to climb the ladder: whoever invites a member, changes a member's role or creates/edits a custom role can only hand out permissions they hold themselves, nobody can change their own role, and a member can only be changed or removed by someone at least as powerful (an owner can only be touched by another owner). Organization-level controls (rename/deactivate the organization, audit trail, project access management) stay with the built-in owner/admin roles and cannot be put into a custom role. Custom role names must be non-blank, cannot reuse a built-in role name, and a role needs at least one permission.

Project-level access grants

Owners and admins always have full access to every project in their organization. For everyone else, access to a given project's resources (agents, flows, knowledge bases, MCP servers, gates) is closed by default and opened only through an explicit grant, scoped to that one project:

  • A role grant extends a permission set to every member holding a given built-in role (member/viewer) or custom role, for that project only.
  • A member grant extends a permission set to one specific member, for that project only — useful for exceptions that don't warrant a new custom role.

Grants can only include permissions that make sense to delegate — a fixed set of organization-level permissions (like managing billing or deleting the organization) can never be handed out this way, at either the custom-role or project-grant level.

A role or member grant can also be narrowed further to a specific subset of records within a resource type — for example, a member grant with FLOW_READ/FLOW_UPDATE can be restricted to only two named flows out of a project's ten, instead of all of them. This record-level restriction is enforced everywhere: list endpoints only return in-scope records, and direct access to an out-of-scope record's ID is rejected even though the grant otherwise holds the required permission. A grant with no such restriction on a resource type continues to see every record of that type, matching the platform's default (all-or-nothing) behavior.

API keys and connected apps

Consumer API keys carry scopes (resource:action, for example flows:write). A key is created with one of four presets — Read only, Read & execute, Builder, Full access — and only Full access includes deletes, provider management, settings changes and gates (connected apps get it only when write access is enabled for them; the assistant never does). A key is never created without an explicit access level: a request that names neither a preset nor scopes is rejected instead of defaulting to full access. Keys created before scopes existed keep full Consumer REST access (legacy_full), except for gates, but are not accepted on the MCP endpoint. For keys with scopes, writes also require that the key's creator still holds the matching project permission; a key whose creator left the organization can no longer write.

The gates:read, gates:write and gates:delete scopes (see Gates & Channels) are opt-in: no preset except Full access contains them, and the assistant never receives them, because gates configure public-facing channels. A key or connected app gets them only through explicit scopes or the Full access preset.

Personal access tokens (uo_pat_..., created under Settings → Access tokens) are user-level credentials bound to one organization rather than a project. Like OAuth grants, they act as their owner: each call checks the owner's live role and project access (the same rules as the dashboard), so a token can never exceed its owner and loses power the moment the owner does. On project endpoints the target project is verified to belong to the token's organization and to be accessible to the owner before anything runs. There are no per-token scopes to choose. Only a hash is stored; the secret is shown once.

The API apps add X-Content-Type-Options: nosniff, Referrer-Policy: no-referrer, Strict-Transport-Security and, on JSON responses, a Content-Security-Policy of default-src 'none'; frame-ancestors 'none'.

Apps connected through OAuth (see MCP) get one grant per user and project. The OAuth server issues opaque, hashed-at-rest tokens: authorization code with mandatory PKCE (S256), one-hour access tokens, rotating 30-day refresh tokens whose reuse revokes the grant, and exact redirect_uri matching. Only public clients are supported. Each call is checked against the user's live permissions, so a grant can never exceed what its owner can do.

Files sent with messages

Attachments are user-supplied and treated as untrusted.

  • Opt-in on public surfaces. Share links, the Web Widget, Slack and WhatsApp take files only when their owner switches it on, and then with tighter limits than signed-in surfaces. Uploads are rate limited per visitor.
  • Bound to who sent them. An uploaded file can only be attached by the party that uploaded it (a user, an API key's project, a share link, a widget conversation) and only inside the same project and organization; anything else answers as "not found". Uploading to a project requires the project to belong to the caller's organization and the execute permission.
  • Data, not instructions. File text reaches a flow or agent inside marked blocks introduced by a notice that it must never be followed as instructions; closing tags inside a file are defused and file names are escaped.
  • Bounded parsing. Size, text length and spreadsheet rows are capped, archive formats are refused when they would expand absurdly, and extraction runs with a time limit.
  • Safe downloads. Originals are always served as a download (application/octet-stream, nosniff) and only to members with access to the project. Channel downloads send the channel's access token only to the channel's own hosts.
  • Retention. Files are kept for 30 days after they were sent (24 hours when never sent), then deleted from storage and the database.

The AI assistant

The in-app assistant acts with the same capabilities as a Builder-level connected app (plus deleting documents), but only on behalf of the signed-in organization member and only inside the project they have open; platform administrators cannot use it. Every action is checked against that member's permissions at the moment it runs, so it can never exceed them.

  • Anything that changes or runs something is shown with its exact arguments and runs only after approval; permanent deletions always ask, even with auto-approve on.
  • Text the assistant reads (tool results, document contents) is treated as data, never as instructions, and it never asks for, accepts or repeats secrets.
  • It runs on a platform-operated model with a per-organization monthly token quota; the model credentials are never exposed to organizations.
  • The server keeps no conversation; the browser resends the transcript on each turn, and a message cannot carry a system role.

Audit trail

Changes to flows, agents and knowledge documents (from the UI, an API key, a connected app or the AI assistant) and MCP server registrations made by a connected app or the assistant are recorded with who (user, key or app, and the person behind it), through which surface, what changed (secret-free summaries) and when. Owners and admins can read the trail per project (AUDIT_READ).

Secrets & encryption

  • Provider credentials (API keys and connection secrets) are encrypted at rest using industry-standard encryption, and are never exposed in any API response — not even to the organization admin who created them.
  • Channel credentials entered on a gate (for example a messaging app's token or signing secret) are protected the same way and are write-only: responses only list which credentials are set.
  • The platform has no default or placeholder secrets — every secret must be explicitly configured before the system will run.

Tenant isolation

Every organization's data — projects, agents, flows, executions, and knowledge bases — is isolated from every other organization's data at the storage layer, not just at the application layer. See Multi-tenancy for details.

Public chat surfaces

Push channels such as Slack call a public webhook instead. Every call must carry a valid signature made with the gate's own signing secret and a fresh timestamp (replays are rejected); unsigned or wrongly signed calls are refused before anything runs, retries are de-duplicated, and a per-sender rate limit applies.

The Web Widget is the one surface an anonymous visitor talks to. A visitor's only identity is a signed, expiring conversation token; the gate, flow, organization and project are always derived server-side, never from what the visitor sends. Where the widget may be embedded is enforced by the browser (a per-gate frame-ancestors policy), messages are rate limited, a run can be streamed only once and only by the conversation that started it, and visitors never see raw flow errors.

Responsible AI safeguards

User-supplied input is screened for prompt-injection attempts before it reaches a model, and any user-authored logic — such as flow branching conditions — is evaluated in a restricted, sandboxed manner rather than executed as arbitrary code.

  • Multi-tenancy — how tenant isolation is enforced beyond role-based authorization

Voice and phone calls

  • Public voice entry points are bounded: allowed websites, optional single-use tokens minted by your backend, per-gate simultaneous-call, length and minute limits.
  • Carrier credentials are encrypted like provider keys and never returned. The telephony server reads rendered configuration from a memory-backed volume; nothing with a decrypted password is written to disk or logs.
  • Phone traffic is allow-listed: calls from addresses outside a carrier's list are refused, a carrier only reaches the numbers of its own gates, and outbound calls and transfers are limited to the gate's destination prefixes.
  • Internal services (voice workers, the telephony bridge, the telephony server's control interface) are never published and authenticate with a shared internal key.

On this page