# How Do Permissions Work in an AI Workspace?

AI workspace permissions control what people and autonomous agents can search, read, and modify across enterprise documents. Traditional folder access lists fail during semantic retrieval because chunked embeddings drop nested inheritance rules. Enforcing permissions at the container level isolates retrieval to specific workspaces and shares, preventing sensitive data leaks.

Source: https://fast.io/resources/ai-workspace-permissions/
Author: [Tom Langridge](https://fast.io/authors/tom-langridge/)
Last reviewed: 2026-11-09

## Why Traditional Folder ACLs Fail in an AI Workspace

An AI assistant connected to an enterprise document repository will eventually summarize a confidential document for someone who was never allowed to open it. The failure is not a flaw in the language model; it is an architectural mismatch between traditional folder access control lists and semantic vector retrieval. Traditional file systems rely on deep directory trees where folders inherit or override permissions across complex user groups. When an AI indexing pipeline ingests those files, it breaks documents into text chunks, calculates vector embeddings, and stores them in a high-dimensional index. In that translation, the nested inheritance rules that protect payroll spreadsheets and executive strategy memos break down.

When an indexing pipeline chunks a document into short passages, the folder path is frequently detached or simplified. Storing and evaluating deep access control lists next to millions of individual vector points creates massive operational overhead. Even if security tags are stored beside each vector, keeping those tags synchronized with directory permission changes is prone to failure. If an administrator alters access on a parent directory, the underlying vector index continues to hold outdated permission tags until an expensive re-indexing job completes.

This architectural mismatch forces retrieval engines into one of two flawed evaluation strategies:

1. **Post-Hoc Filtering (Relevance Collapse):** The vector database runs similarity search across the entire tenant corpus to find semantically relevant chunks. After retrieval, the application checks whether the asking user has permission to read the source file. If the most relevant chunks belong to restricted documents, the application discards them, leaving the language model with marginal passages or none at all. The assistant either hallucinates an answer or claims the information does not exist, even though relevant documents sit in the repository.
2. **Pre-Filtering Across Deep ACL Trees:** The search engine attempts to filter millions of vector chunks against dynamic, nested user groups before calculating cosine similarity. Evaluating complex inheritance trees at query time introduces substantial search latency, degrades response times, and fails when permission graphs exceed database query limits.

Container isolation eliminates this dilemma. By aligning the retrieval boundary with the storage container itself, an AI search query answers only from the containers the asker belongs to.

### Why Traditional Folder ACLs Fail in Semantic Retrieval

Traditional file systems rely on Access Control Lists (ACLs) applied to hierarchical folders. A root folder might be visible to the entire company, while subfolders for human resources, finance, and legal carry custom deny rules or broken inheritance flags. For human users browsing a directory tree, this model functions predictably because the operating system or cloud drive evaluates permissions sequentially as the user drills down through folders.

Vector databases do not browse folders. When files are converted into embeddings for Retrieval-Augmented Generation (RAG), the spatial hierarchy of directories disappears. The vector index treats embeddings as points in a mathematical space organized by conceptual meaning rather than directory structure.

Attempting to enforce folder-level permissions inside a vector store introduces severe synchronization drift. If an IT team moves a folder or changes a group membership, every chunk derived from every file within that directory tree must have its metadata updated. In large document collections containing hundreds of thousands of chunks, propagation delays leave sensitive passages queryable by unauthorized users long after directory permissions were revoked.

Furthermore, human errors in folder nesting represent a frequent vector for unintended data exposure. When permissions are configured deep within nested subdirectories, administrators easily lose visibility into which groups inherit access. If an employee accidentally moves a sensitive spreadsheet into a folder with broader permissions, or breaks inheritance on a subfolder to share a single report, the change cascades silently into the vector index. In an AI workspace, that single misplaced file becomes immediately discoverable to any assistant querying the corpus.

### The Relevance Collapse of Post-Hoc Permission Filtering

Post-hoc filtering is a common anti-pattern in early AI workspace deployments. Because attaching dynamic permissions to vector embeddings is difficult, systems query the entire vector store for the nearest semantic neighbors and filter out unauthorized documents in application logic before passing context to the model.

This approach creates two dangerous failure modes:

* **Relevance Starvation:** An assistant configured to retrieve the top chunks might find that almost all chunks reside in restricted files. After discarding the unauthorized material, the model receives a single out-of-context passage. It then generates an incomplete or misleading summary because the primary context was stripped away.
* **Information Leakage via Error States and Citations:** When an assistant states that it found relevant documents but cannot display them due to permission restrictions, it confirms the existence of confidential projects, mergers, or investigations. In poorly configured systems, cached chunk titles or document filenames leak into the chat response even when chunk text is blocked.

The alternative is container-based isolation in [intelligent workspaces](/product/workspaces/). When permissions are established at the container level, every document within the container shares the same access baseline. Search and AI answer only from the workspaces and shares the user is a member of, so results do not have to be filtered document by document after retrieval.

## How Permissions Work in an AI Workspace Container Model

To solve the structural flaws of nested folder ACLs in AI retrieval, modern workspaces use container-based access control. Rather than scattering permission rules across individual files and subdirectories, access is governed across three clear tiers: the Organization, the Workspace, and the Share.

Each tier defines an explicit boundary for administrative control, member roles, and semantic retrieval. Inside a workspace, there are no folder-level or file-level permissions. Every member invited to a workspace reaches all files and folders inside that workspace according to their assigned role. When sensitive files must be restricted from certain team members or autonomous agents, those files are placed in their own dedicated workspace or a separate share.

This architecture creates an absolute retrieval boundary: semantic search and [workspace AI features](/product/ai/) answer only from the workspaces and shares the asking person or agent is an active member of. By eliminating nested inheritance within the retrieval domain, teams achieve predictable data boundaries without managing complex ACL graphs.

### Organization Boundary: Governance and Account Control

The Organization is the top-level administrative container representing the company or business entity. It owns account subscriptions, storage allowances, AI credit pools, and global settings.

Organization-level permissions are managed through member roles:

* **Owner:** Holds full administrative control, manages billing and subscriptions, invites administrators, and oversees all organization assets.
* **Admin:** Manages organization members, creates workspaces, and configures organization-wide preferences.
* **Member:** Standard user identity that can join workspaces whose join setting allows it, as well as any workspace it is invited to.

Being an organization member does not by itself grant visibility into workspace data. Each workspace's join setting controls which organization members can join it; by default, any organization member can. An organization administrator can view workspace existence, but workspace content and AI retrieval remain restricted to users and agents who are members of that specific workspace.

### Workspace Boundary: The Primary Team and Retrieval Domain

The Workspace is the primary collaboration and storage container for projects, departments, or client matters. Fastio enforces permissions at the workspace level through member roles.

Inside a workspace, permissions are uniform across all directories. There are no folder-level permissions, no file-level access control lists, and no hidden subdirectories. Every member of a workspace can view, read, and interact with all files inside that workspace according to their workspace role.

This container model provides critical advantages for AI workflows:

* **Predictable Retrieval Scopes:** When Intelligence Mode is enabled on a workspace, semantic search indexes all files in that workspace. When a user or agent submits a question, search answers only from the workspaces and shares that person or agent belongs to, so results do not include content from an adjacent department's workspace unless the asker is also a member there.
* **Zero ACL Graph Traversal:** Because all members of a workspace share access to the workspace contents, vector queries do not require slow, complex permission graph evaluations at query time. Retrieval is fast, deterministic, and complete.
* **Clean Partitioning for Sensitive Material:** If human resources files, legal records, or executive compensation spreadsheets must remain restricted, they are not tucked into a hidden folder within a general team workspace. They are placed in a dedicated HR or Legal workspace with its own member roster. Autonomous agents and human staff are added only to the specific workspaces their work requires.

### Share Boundary: Targeted External and Cross-Team Delivery

The Share is a specialized container created from a workspace to distribute files externally or collaborate across teams without granting full workspace membership. Fastio supports branded shares (Send, Receive, and Exchange) that can be durable or expiring, configured with per-recipient access, and protected with download restrictions.

The Share acts as an independent retrieval container:

* **Isolated AI Answers:** When an AI assistant or search interface is enabled on a share, it answers questions exclusively using the files contained within that specific share. It cannot see, index, or cite any file from the parent workspace that was not explicitly included in the share.
* **No Account Required for Link Recipients:** External clients opening a share link can review documents and query share contents without consuming an organization seat.
* **Download Controls:** An administrator can disable file downloads on a share, allowing external parties to read documents and interact with AI search in the browser while preventing local file exports.

### Summary of Container Permission Tiers

The table below outlines the three container tiers, their access boundaries, and how they govern AI retrieval:

| Container Tier | Access Boundary | Access Controls | Retrieval Scope | Recommended Use Case |
| :--- | :--- | :--- | :--- | :--- |
| **Organization** | Entire company tenant | Owner, Admin, Member | Account administration; workspace content requires workspace membership | Managing billing, storage quotas, seats, and high-level governance |
| **Workspace** | Department, project, or matter | Owner, Admin, Member, Guest, View | Semantic and metadata search across all workspace files | Daily team collaboration, agent execution environments, client matters |
| **Share** | Selected files or designated folder | Link recipient, named recipient, password protection | Strictly bounded to files included in the share; zero parent access | External client delivery, vendor file collection, public documentation |

## How Cloud Sync and External Connectors Inherit Permissions

Enterprise teams rarely maintain documents in a single platform. Most organizations operate substantial repositories across Google Drive, Dropbox, Box, and OneDrive, alongside SharePoint document libraries connected through OneDrive connectors. Connecting an AI assistant directly to these legacy drives often creates severe compliance risks because years of ad-hoc folder sharing have left confidential files exposed to broad internal groups.

Fastio bridges existing storage systems into AI-ready workspaces through Cloud Sync and one-time cloud imports. Understanding how permissions translate across these connections is essential for maintaining secure retrieval boundaries. In an intelligent [company brain](/product/company-brain/), files synchronized from external drives take the Fastio workspace's permissions, ensuring that source drive misconfigurations do not compromise agent workflows.

### Decoupling External Drive Permissions from Workspace Retrieval

When files synchronize into an AI workspace from an external drive, permission inheritance does not carry over. Files synced through Cloud Sync from Google Drive, Dropbox, Box, or OneDrive take the Fastio workspace's permissions. The source drive's sharing settings, inherited folder ACLs, and legacy sharing links are discarded upon entry.

This decoupling is a deliberate security decision:

* **Eliminating Permission Rot:** Legacy cloud drives accumulate orphaned sharing links, former contractor permissions, and broad company-wide access grants. If an AI assistant attempted to evaluate those legacy permissions during retrieval, security risks would multiply.
* **Deterministic AI Scope:** What a person or autonomous agent can retrieve in Fastio is determined entirely by their Fastio workspace membership, not by historical settings in Google Drive or SharePoint.
* **Isolated Cloud Sync Folders:** If an engineering team syncs a Google Drive folder into an Engineering workspace, only members of that Fastio Engineering workspace can search or query those files with AI. Other teams in the organization cannot search the synced data unless they join or are added to that workspace.

### Sync Schedules, Provider Support, and One-Time Imports

Cloud Sync connects Google Drive, Dropbox, Box, and OneDrive folders to a workspace, one-way or two-way, on a schedule or on demand. Cloud Sync never runs continuous, live, or real-time sync loops.

For static archives, completed projects, or regulatory records that do not require ongoing synchronization, Fastio provides one-time cloud import. Teams can import folders from Google Drive, Dropbox, Box, or OneDrive through a one-time cloud import, or bring in files from public URLs with URL import, without routing files through local storage. Once imported, the files reside natively within the Fastio workspace, indexed for semantic search and protected by workspace container permissions.

## How to Scope Agent Credentials and Machine Access

Autonomous AI agents and interactive assistants interact with workspaces differently than human users. While humans navigate web dashboards and click visual controls, agents execute programmatic calls across APIs and context protocols. Giving an AI agent unfettered administrative credentials creates severe operational hazards, including unintended file modifications, accidental deletions, or unauthorized data retrieval. According to the OWASP GenAI Security Project, excessive agency enables damaging actions to be performed in response to unexpected or manipulated outputs from a language model.

Fastio provides a remote Model Context Protocol (MCP) server over Streamable HTTP, alongside a structured REST API at `https://api.fast.io/current/`. Securing agent access requires selecting the appropriate endpoint, enforcing least-privilege credential scopes, and using concurrency controls. Developers can review the complete setup walkthrough in the [Fastio MCP documentation](https://mcp.fast.io/docs) or deploy dedicated [persistent agent storage](/storage-for-agents/) tailored to automated workers.

### Interactive Human Sessions via OAuth and Streamable HTTP

Interactive agents operate within desktop applications, terminal tools, and IDEs where a human user directs the conversation. Examples include Claude Desktop, Claude Code, Cursor, Cline, Devin, and VS Code agent mode.

Interactive agents connect to Fastio using Streamable HTTP at dedicated endpoints:

* **Claude and General Clients:** Connect via `https://mcp.fast.io/mcp/tools`.
* **Coding Agents:** Connect via `https://mcp.fast.io/mcp/code` in tools like Claude Code, Cursor, Cline, and VS Code.
* **ChatGPT and Codex:** Connect using the Fastio plugin from the ChatGPT plugin directory, or configure custom MCP servers at `https://mcp.fast.io/mcp/operations`.

As defined in RFC 6749, the OAuth 2.0 authorization framework enables a third-party application to obtain limited access to an HTTP service. Rather than embedding long-lived API secrets into client configuration files, the user logs in through a secure browser consent window. During sign-in, the user reviews a permissions screen that enforces two explicit boundaries:

1. **Access Level:** The user selects whether the client receives Read Only or Read & Write permissions.
2. **Container Scope:** The user explicitly checks which organizations and workspaces the connection is allowed to reach.

The intersection principle strictly governs the interaction: an interactive agent's effective authority equals the intersection of its OAuth scope and the human user's workspace role. If a user does not have access to a Finance workspace, their assistant cannot search or retrieve financial documents, regardless of how the user phrases the prompt.

### Autonomous Background Agents and Scoped API Keys

Autonomous agents run in background workers, scheduled pipelines, and cloud sandboxes without an interactive human user. Examples include nightly document extraction bots, continuous integration agents, and multi-agent coordination frameworks.

Because headless agents cannot complete a browser OAuth screen, they authenticate using scoped API keys sent as an HTTP header: `Authorization: Bearer <api key>`.

Scoped API keys must never be generated from personal user accounts. Instead, administrators configure dedicated machine credentials scoped to specific workspaces, with read or read-write access for each:

* **Read-Only Indexing Agents:** An agent assigned to analyze industry research needs only Read Only access to a Research workspace.
* **Ingestion and Processing Agents:** An agent extracting structured data via [Metadata Views](/product/document-data-extraction/) receives Read & Write access limited strictly to the Ingestion workspace where new files arrive.
* **Tool Separation:** On `https://mcp.fast.io/mcp/tools`, read operations stay on read tools (`storage`, `workspace`, `share`), while mutations require `_manage` tools (`storage_manage`, `workspace_manage`, `share_manage`). This separation allows developers to audit and restrict tool calling at runtime.

### Advisory File Leases and Safe Concurrent Writes

When multiple autonomous agents or human teammates write to the same workspace, concurrent file modifications can cause race conditions. Fastio provides advisory per-file locks in workspace and share storage.

Agents manage locks programmatically through MCP tools:

* `lock-acquire` on the `storage_manage` tool to request a lease before editing.
* `lock-release` on the `storage_manage` tool upon completing the write operation.
* `lock-status` on the `storage` tool to inspect current holders.

A file lock is advisory: it indicates active work and expires automatically unless heartbeated by the holder. It never grants exclusive write locks or blocks concurrent writes entirely. If two agents write simultaneously, both writes land safely, and per-file version history preserves every version so that no data is silently overwritten.

### Agent-to-Human Ownership Transfer

In modern automated setups, an autonomous agent can bootstrap an entire organization. An agent can create an organization, configure workspaces, establish shares, and populate reference documentation.

Once the environment is constructed, the agent can execute an ownership transfer, handing primary organizational ownership to a human stakeholder. The agent retains its administrative role to continue executing scheduled maintenance, while legal and billing control transitions to the human owner.

## How Activity Auditing and Governance Protect Workspaces

Deploying AI in enterprise environments requires accountability. IT leaders and security teams must know who modified permissions, which agents created shares, and when documents were updated. Container-based workspaces provide governance through detailed mutation tracking, version history, and granular delivery controls.

When autonomous agents and human specialists collaborate inside shared containers, system state evolves rapidly. An automated worker might process incoming customer records, generate summary briefs, and adjust sharing parameters during off-peak hours. Without transparent auditing, administrators cannot reconstruct the sequence of actions that preceded an operational issue. Fastio addresses this requirement by recording every state modification directly in an organization-level activity log.

By maintaining a clear audit trail of administrative modifications and file mutations, teams keep their workspace environments observable and recoverable without exposing sensitive file contents across unverified retrieval boundaries. For teams evaluating multi-seat deployments, reviewing [workspace pricing and plans](/pricing/) provides clear insight into seat allocations and credit allowances.

### The Detailed Activity Log: Tracking Changes and Configurations

Fastio maintains a detailed activity log that records mutations and administrative actions across the organization. The log tracks actions executed by human users and automated agents alike.

The activity log records:

* File uploads, edits, moves, and deletions.
* Organization membership changes and role assignments.
* Workspace creations, membership updates, and role modifications.
* Share creations, updates, and configuration adjustments.

The activity log is an audit of mutations and system state changes, not an access log. It does not record read-only events such as file views, previews, opens, or downloads. Tracking modifications provides a clear, reliable history of how workspaces and permissions evolve over time without storing petabytes of passive viewing telemetry.

### Version History and Accidental Mutation Recovery

Language models and autonomous scripts can introduce errors, from broken text formatting to accidental overwrites. Fastio maintains complete per-file version history across all workspaces.

Every upload, API edit, or file replacement creates a discrete version. If an agent executes an unintended modification or overwrites a project brief with an erroneous summary, administrators can inspect the historical timeline and restore previous versions immediately. Version history operates alongside advisory file locks to ensure that multi-agent collaborative editing remains resilient and recoverable.

### Share-Level Download Restrictions

Sharing documents with external clients, partners, or vendors often requires balancing accessibility with data protection. While Fastio does not offer watermarking, a share can disable file downloads.

When download restrictions are enabled on a share:

* External recipients can view documents and inspect contents directly in the web viewer.
* Recipients can use built-in AI search and Intelligence chat to query the shared files.
* Direct file download and local export buttons are disabled in the interface.

This mechanism allows organizations to deliver interactive, AI-queryable document sets while keeping physical files contained within the share.

### Platform Security Architecture

Fastio runs on cloud infrastructure partners, including Google Cloud Platform and Cloudflare, that are certified to industry-leading security standards.

Within the workspace platform, customer data is protected through defense-in-depth features:

* **Encryption in Transit and at Rest:** All network traffic is encrypted in transit using modern TLS protocols, and stored files are encrypted at rest.
* **Scoped Authentication:** Access tokens, OAuth scopes, and API keys are strictly confined to designated containers and operational actions.
* **Workspace Isolation:** Logical container separation prevents cross-tenant and cross-workspace retrieval cross-talk.
* **Role-Based Permissions:** Every workspace and share enforces explicit role boundaries across all human and machine members.

## Frequently asked questions

### How do permissions work in an AI workspace?

Permissions in an AI workspace are enforced at the container level across organizations, workspaces, and shares using role-based access. Rather than evaluating individual file or folder rules during retrieval, semantic search and AI assistants operate strictly within the boundaries of the workspaces and shares the user or agent belongs to.

### Do AI assistants inherit folder-level permissions?

No. AI assistants do not inherit folder-level or file-level permissions because workspaces do not use folder or file access control lists. Every member of a workspace can access all files inside that workspace according to their role. If sensitive files must be restricted from certain team members or agents, they should be placed in a separate workspace or a dedicated share.

### What is container-based access control in AI?

Container-based access control is a security architecture that isolates storage, indexing, and retrieval boundaries to discrete containers, such as workspaces or shares. Search and AI answer only from the containers the asker is a member of, so queries do not retrieve content from other containers, removing the data leakage caused by broken folder inheritance.

### How do permissions work when syncing files from Google Drive or OneDrive?

When files synchronize into a workspace from Google Drive, Dropbox, Box, or OneDrive via Cloud Sync, they take the Fastio workspace's permissions. The source drive's sharing settings, guest links, and folder ACLs do not carry over. Access to the synced files is governed entirely by Fastio workspace membership.

### Can an AI assistant access files across different workspaces?

An AI assistant can only access files from the specific workspaces and shares that its connection is authorized to reach. For interactive assistants, the user selects authorized workspaces during OAuth sign-in. For autonomous agents, the scoped API key is explicitly restricted to designated workspaces. The AI cannot search or retrieve across unauthorized workspace boundaries.

### How do permissions work for autonomous AI agents versus human users?

Human users and interactive assistants connect via OAuth 2.0 in the browser, where access is bounded by the user's role and selected workspaces. Autonomous background agents connect using a scoped API key passed via an HTTP Bearer token, which limits the agent to the key's workspace scopes and the permissions of the account that created it, without requiring human login sessions.

### Can an external client in a share query the entire workspace with AI?

No. When a share is created with Intelligence enabled, the AI assistant inside that share answers questions exclusively from the files contained within that specific share. The external recipient cannot query, view, or retrieve any other documents from the parent workspace.

### Does the activity log track when an AI assistant reads a document?

No. The detailed activity log tracks modifications and system events, including file uploads, edits, moves, deletions, membership changes, and share creation. It does not record read-only events such as views, previews, opens, or file downloads.

## Sources

- [OWASP GenAI Security Project: Excessive Agency](https://genai.owasp.org/llmrisk/llm062025-excessive-agency/): Excessive agency enables damaging actions to be performed in response to unexpected or manipulated outputs from a language model.
- [IETF RFC 6749: The OAuth 2.0 Authorization Framework](https://datatracker.ietf.org/doc/html/rfc6749): The OAuth 2.0 authorization framework enables a third-party application to obtain limited access to an HTTP service.

## About Fast.io

Fast.io provides shared workspaces where people and AI agents work on the same files, with built-in semantic search and citation-backed chat over what they hold. Agents reach it through a remote MCP server, a REST API at https://api.fast.io/current/, and a command line client published on npm as @vividengine/fastio-cli. MCP setup is at https://mcp.fast.io/docs: Claude and most MCP clients connect to https://mcp.fast.io/mcp/tools, ChatGPT to https://mcp.fast.io/mcp/operations, and coding agents to https://mcp.fast.io/mcp/code.