> For the complete documentation index, see [llms.txt](https://docs.amigo.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.amigo.ai/data/workspaces.md). # Workspaces A workspace is the tenant boundary in the Amigo platform. Each workspace has its own world model, connected data sources, agent and service configurations, and access settings. Public data access is authenticated and scoped to the selected workspace. ## Tenant Isolation ```mermaid flowchart TB subgraph WA["Workspace A"] WMA[World Model] --- SA[Services] SA --- PA[Phone Numbers] PA --- DA[Data Sources] end subgraph WB["Workspace B"] WMB[World Model] --- SB[Services] SB --- PB[Phone Numbers] PB --- DB[Data Sources] end WA ~~~ WB style WA fill:#f5f5f5,stroke:#083241 style WB fill:#f5f5f5,stroke:#083241 ``` Each workspace is an isolated organizational boundary. This means: * Workspace-scoped event reads do not expose another workspace's events * Entity projections are computed per-workspace * Phone numbers, services, and context graphs are scoped to a workspace * API keys authenticate to a specific workspace ### Layered Isolation Public requests authenticate a workspace identity, validate that referenced resources belong to that workspace, and scope supported reads and writes to the same tenant. Data services add storage-level controls where appropriate, while audit records retain workspace and actor attribution. Some trusted platform workers intentionally process more than one workspace, such as schedulers and connector workers. Those paths use service credentials and preserve explicit workspace scope; they are not public unscoped access. Treat isolation as a layered authorization contract rather than assuming every table uses one identical enforcement mechanism. For healthcare organizations, this isolation model supports multi-site deployments where each clinic, department, or practice operates as its own workspace with its own data and configuration. A hospital system with five clinics can run five workspaces, each with its own EHR connector, phone numbers, and scheduling logic. ## API Keys and Permissions API access is scoped to an account within a workspace. Each account has a role that determines what it can do: | Role | Capabilities | | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Owner** | Admin permissions plus the ability to create owner-role API keys. | | **Admin** | Can update and delete workspace resources, manage members and API keys, query privileged analytics, view audit data, and delete a workspace. | | **Member** | Read access plus supported resource creation, clinical data writes, outbound conversation starts, channel sends, and trigger management. | | **Operator** | View access plus operator actions: monitor and take over eligible runs, send guidance, author supported text turns, and claim or decide external write proposals where the private-preview review flow is enabled. | | **Viewer** | Read-only access. Can view configurations, data, and call records but cannot modify anything. | When creating an API key, the caller selects a role and may optionally narrow it to a subset of that role's permissions. The requested role and permissions cannot exceed the creator's own access, and only an owner can create an owner-role key. ## Environment Separation {% hint style="warning" %} Never test agent behavior changes directly in a production workspace. Use staging workspaces to validate changes before promoting them to production. {% endhint %} Most organizations use multiple workspaces to separate regions: | Environment | Purpose | | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Production** | Live workloads and production integrations. New identity sessions use the configured production idle-timeout policy. | | **Staging** | Pre-production testing with production-like configuration. New identity sessions use the configured non-production idle-timeout policy. | | **Development** | Building and testing new context graphs, skills, and integrations, typically with synthetic data or sandbox integrations. New identity sessions use the non-production timeout policy. | This separation ensures that changes to agent behavior, safety rules, or data integrations can be tested in staging before they affect real patient interactions in production. The Platform API can update a workspace's environment label, and a dedicated staging/production conversion flow is available through the API and Developer Console with slug confirmation and advisory warnings. The environment is consulted when new identity sessions receive their idle-timeout policy. Conversion does not migrate the workspace to another region, retroactively change existing sessions, or by itself certify a HIPAA or HITRUST control posture or alter audit retention. Validate those controls separately before using real patient data. ## What Lives in a Workspace A workspace contains all the resources needed to run a deployment: * **Services** - Define which context graph and agent configuration handle calls * **Phone numbers** - Routed to services within the workspace * **Data sources** - Configured EHR, FHIR, database, file, and API integrations plus connector runner settings * **World model** - The event store and entity projections for this workspace * **Agent configuration** - Authored behavior, context graphs, models, functions, and channel-specific settings * **Voice settings** - TTS voice selection, speed, keyterm lists, sensitive topic configuration * **Operator configuration** - Which operators can join calls and how escalation works * **Security settings** - Optional workspace-level security controls and access policies {% hint style="info" %} **Developer Guide** - For API endpoints, SDK examples, and integration details, see the [Workspaces](https://docs.amigo.ai/developer-guide/platform-api/workspaces) section of the developer guide. {% endhint %} --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.amigo.ai/data/workspaces.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.