Access and safety
Understand sign-in, channel boundaries, query modes, and the limits of a connection.
A Twin connection carries your identity to a bounded interface. Discovery and
typed deterministic queries are read-only. A natural-language question that may
change workspace data (the writeback capability, granted by default) requires
both twin.query and twin.write; one asked with readonly-data alone needs
only twin.query. Direct posts,
comments, reactions, records, and saved-view updates also require twin.write.
That scope does not give an assistant general access to your workspace or server.
What sign-in decides
The service derives the following from the signed-in identity and administrator-managed mapping:
- the active user;
- the upstream and Twin organisations;
- the permitted OAuth scopes;
- the correct tenant control plane; and
- the channels that user may access.
A query cannot supply or override those values. Missing, disabled, or mismatched mappings fail before execution begins.
What stays internal
Internal data bindings and model policy remain server-controlled. A session
query can request a bounded set of capabilities, which the service checks
against tenant policy. When omitted, the requested capabilities are
readonly-data and writeback; a natural-language question is not a read-only
guarantee unless it asks for readonly-data alone. The CLI's --allow-write
flag guards direct CLI mutations, not writes performed within a routed session.
Over MCP the two are separate tools. twin_query is labelled read-only: its
typed queries read, and its questions always run with readonly-data alone.
twin_task is labelled as a write: its questions run with the capabilities
they name (readonly-data, writeback, web-research), by default
readonly-data and writeback. Hosts that ask before a write tool runs ask
before twin_task. With web-research, the web is searched only when the
question asks, as in "search the web for…" or "check their website". A search
carries only the question's own words and public names, never details from your
organisation's records.
Natural-language queries use the same persisted session router as the web app. Typed deterministic queries skip model interpretation, but still use the same identity, channel access, organisation scoping, and server-owned data binding.
What the assistant can do
| Allowed | Not available |
|---|---|
| List channels available to the signed-in user | Discover other tenants or organisations |
| Inspect a channel's queryable object and field schema | Select internal products or relations |
Ask a natural-language question through the canonical router (twin_query to read, twin_task to act) | Select arbitrary models, prompts, tools, or routing |
| Submit a typed records, aggregate, or saved-view intent | Submit raw SQL or override organisation scope |
| Read channel activity, members, and flat threads | Discover an organisation-wide people directory through a channel |
Publish an approved post, comment, or reaction with twin.write | Publish internal reasoning or silent progress updates |
Add an approved native record with twin.write | Create source-backed rows or silently infer a write |
| Publish an approved view definition against its inspected version | Overwrite a newer view definition |
| Check a routed query and open an authenticated channel link | Read unrelated sessions, raw events, or model configuration |
| Submit feedback the user provided or confirmed | Infer feedback or submit it without the user's knowledge |
As an organisation admin, prepare and run Twin Build and list the Twin's definitions (twin_build_*) | Run Twin Build or read definitions without an admin role |
Read and decide proposals as the web app allows (twin_proposal*) | Accept a proposal its policy reserves for admins |
The recorded interface type—api, cli, or mcp—is audit metadata. It never
grants authority or creates a separate execution policy.
Your other provider still matters
ChatGPT, Claude, Codex, or another provider receives the question and tool result under that provider's own data controls and retention terms. Twin access controls do not replace your organisation's review of that provider.
Who chooses the model
The connected assistant or end user does not select an arbitrary model for a Twin query. Model routes are configured for the deployment and evaluated for their intended tasks.
Keeping model routing server-side means an organisation can choose an approved model suited to the work, or move to another configured provider, without changing the public query contract. Cost, retention, capability, and quality remain part of the deployment decision.
Never share credentials in a prompt
Sign in through the protected browser screen. A support person or agent should never ask you to paste a token, client secret, password, cookie, SSH key, or Tailscale credential into a conversation.