Storage and scoping define which Octo records belong to the whole instance, which belong to a space, and how product pages map to backend models.
| Term | Definition |
|---|
| Instance | The top-level isolated Octo environment for an organization or tenant. |
| Space | A working context inside an instance for product records such as workflows, tools, contacts, phone numbers, dashboards, and interactions. |
| System record | A record that affects platform administration, access, or configuration. |
| Space-scoped record | A record owned by the active space. |
| Model | Backend representation of a product record. |
| Action | Description |
|---|
| Choose the right scope | Decide whether a record belongs to account administration or to a space. |
| Map UI pages to models | Understand which records an integration is likely reading or writing. |
| Avoid data leaks | Keep external integrations constrained to the intended instance and space. |
| Debug missing records | Check active space, permissions, and model ownership before assuming data is absent. |
| Level | Examples | Notes |
|---|
| Instance | Subscription, credits, usage rollups, spaces | Account-level boundary for billing and administration. |
| System settings | Users, roles, permissions, API keys, audit logs, environment settings | Administrative records that may affect the whole instance. |
| Space | AI Workflows, Entry Points, Tools, Knowledge Sheets, Interactions, Contacts, Phone Numbers, Dashboards, Widgets | Product work usually happens inside the active space. |
| Runtime record | Workflow executions, interaction messages, tool calls, recordings | Created as workflows and channels run. |
| Product area | Likely model scope | Notes |
|---|
| AI Workflows | Space | Workflow containers and workflow versions execute in the active space. |
| Entry Points | Space | Channel endpoints route to published workflow versions. |
| Tools | Space | REST API and Script tools are configured for workflow use. |
| Knowledge Sheets | Space | Sheet rows and headers are referenced by workflows. |
| Interactions | Space and runtime | Conversation records link back to entry points and workflow versions. |
| Contacts | Space | Transfer endpoints are available to workflows in the space. |
| Phone Numbers | Space and telephony provider | Purchased numbers are assigned to voice entry points. |
| Dashboards and Widgets | Space | Dashboard layouts and scripted widgets display scoped data. |
| Users and Roles | System settings | Access-control records govern who can operate in the instance. |
| API Keys and Audit Logs | System settings | API keys authenticate integrations; logs record administrative changes. |
| Credits and Usage | Instance with space breakdowns | Billing data is account-level but can be filtered by space and workflow. |
- Resolve the target instance and space before reading or writing product records.
- Use API keys with the least access needed for the integration.
- Keep external IDs in context or metadata so records can be reconciled later.
- Avoid copying records between spaces unless the product workflow explicitly supports import/export.
- Review Audit Logs for system changes and Interactions for runtime behavior.
| Symptom | Likely cause | Check |
|---|
| Workflow is missing | Wrong active space or insufficient permission | Space switcher, workflow list filters, assigned roles. |
| Entry point has no workflow versions | The workflow has no published version in that space | Publish the workflow version first. |
| Tool works in test but not in workflow | Different field values or runtime context | AI fields, template variables, interaction execution path. |
| Usage totals differ from page filters | Account-level totals are being compared with space-level filters | Date range, space filter, workflow filter. |
Are spaces the same as instances?
No. An instance is the top-level tenant environment. Spaces are working contexts inside that instance.
Do API keys automatically limit access to one space?
API key behavior follows the deployment’s authentication, authorization, and scope handling. Confirm the intended scope before using a key in production.
