Adds enterprise API room template research (IW-1)

enterprise-api-room-template-research/IW-1-enterprise-api-room-template-brief.md

@@ -0,0 +1,90 @@
+# Enterprise API: "Create Mural from Template" — Research Brief
+
+**Author:** Willis Kirkham
+**Date:** 2026-03-12
+**Linear:** IW-1
+
+---
+
+## Summary
+
+An enterprise customer wants to programmatically create rooms and populate them with template-based murals using an API key. The enterprise API already has room and mural creation endpoints, but they are only accessible to Mural global admins — not to enterprise customers. This is a deliberate scope restriction, not a bug or feature flag. Beyond this access restriction, no "create mural from template" endpoint exists, though the capability is fully implemented internally. If the business decides to proceed, the work is straightforward: create new narrow scopes so customers can access these endpoints, and build the missing template instantiation endpoint. Estimated effort is 2–4 days.
+
+---
+
+## What the Customer Needs
+
+The customer wants to automate a workflow their teams currently perform manually: create a room in a workspace, then place a pre-built template mural inside it. This is a provisioning use case — standing up structured collaboration spaces at scale, triggered by an internal system (onboarding, project kickoff, training rollout). It must work with an API key (company-level authentication), not OAuth. The customer has an "admin user" whose identity can attribute the created content.
+
+---
+
+## What Already Works
+
+| Customer Need | Enterprise API Status | Notes |
+|---|---|---|
+| Create a room in a workspace | Exists, but not customer-accessible | Requires an internal-only scope |
+| Create a blank mural in a room | Exists, but not customer-accessible | Same scope restriction |
+| Create a mural from a template | Does not exist | Capability exists in internal/public APIs |
+| Authenticate with an API key | Fully supported | Standard enterprise API pattern |
+| Attribute actions to a specific user | Fully supported | Every write endpoint uses an "owner email" field |
+
+The enterprise API's write endpoints follow a consistent pattern: the request includes an owner email address, the system resolves it to a real Mural user, and that user becomes the creator/owner of the resource. This pattern would carry over to template instantiation without architectural changes.
+
+---
+
+## The Gap
+
+**Access gap.** The enterprise API splits endpoints into two tiers. Nine customer-facing scopes (SCIM, audit log, eDiscovery, reporting, etc.) can be assigned by any company admin. Five internal-only scopes are restricted to Mural global admins. Room creation, mural creation, and workspace management all sit behind a single broad internal-only scope that also governs workspace deletion, migration tools, and content transfer. A feature flag audit confirmed there are no additional gates — no feature flags, no conditional route registration, no entitlement checks. The scope restriction is the sole barrier.
+
+**Feature gap.** Even with access resolved, the enterprise API only creates blank murals. The internal and public APIs both support "create mural from template" as a single operation. The business logic is shared and reusable — the work is wiring it into the enterprise API surface, not building something new.
+
+---
+
+## Feasibility & Complexity
+
+The room and mural creation endpoints already exist and work — they just need new narrow scopes so that enterprise customers (not only global admins) can use them. Every customer-facing endpoint in the enterprise API already follows this pattern: a feature-specific scope that company admins can assign when creating an API key. The work is adding scopes for room and mural operations, updating the key creation logic to make them available, and building the missing template instantiation endpoint.
+
+**Effort estimate:** 2–4 days for an engineer familiar with the codebase. This covers: new scope definitions, key creation logic updates, re-scoping existing routes, one new endpoint file for template instantiation, a request body schema, and tests.
+
+**Permission nuance:** The user specified in the owner email field must either be a member of the target workspace or the template must be in a company template collection. For enterprise customers whose admin user is a workspace member — the expected setup — this is straightforward. Worth validating with the customer.
+
+---
+
+## Product Strategy Considerations
+
+This customer's request sits at the boundary between admin and product capabilities. They are asking for a content operation (create from template) through the admin channel (API key authentication), but the use case — automated workspace provisioning attributed to an admin user — is closer to infrastructure setup than day-to-day content creation.
+
+The internal-only endpoints already straddle this boundary. Room CRUD, workspace CRUD, and mural CRUD exist in the enterprise API today but are not customer-accessible. Adding template instantiation would extend this pattern. The narrow-scope approach keeps this selective — the scope model is granular enough to expose specific capabilities without opening the full set of internal operations.
+
+The precedent question is worth noting. If room and template operations become customer-accessible, customers may subsequently ask for workspace creation, mural archiving, and other internal-only operations. Whether this represents scope creep or an opportunity depends on how Mural wants to position API key-driven provisioning.
+
+There is also a documentation dimension. The existing internal-only endpoints are undocumented. Newly-exposed capabilities could follow the same pattern or be formally documented. Undocumented endpoints still become de facto contracts once customers depend on them — the distinction is primarily about support expectations and stability commitments.
+
+---
+
+## If Proceeding
+
+1. **Scope decision.** Define the new narrow scopes needed (at minimum, one for room operations and one for mural/template operations). This gates all subsequent work.
+2. **Customer validation.** Confirm the admin user has workspace membership in the target workspaces and that templates are accessible via workspace membership or company collections.
+3. **Implementation.** Create new scopes, re-scope existing routes, build the template instantiation endpoint, and write tests. A template listing endpoint may also be needed for programmatic template discovery.
+4. **Documentation decision.** Determine whether newly-exposed endpoints should be added to the developer portal or remain undocumented.
+
+---
+
+## Appendix: Key Technical Details
+
+**The owner email pattern.** Every enterprise write endpoint requires an `ownerEmail` field. The system resolves it to a real Mural user, validates company membership, and uses that user as the actor. There is no synthetic or system user — all content creation is attributed to a real person.
+
+**The permission model.** Creating a mural from a template requires three checks: the user can create murals in the target room, the user has not exceeded active mural quotas, and the user has access to the template. Template access is granted via workspace membership, a public sharing link, the global flag, or company template collection membership.
+
+**The scope model.** Scopes are defined in a central registry and filtered at key creation time based on whether the user is a Mural global admin. Adding a new scope requires: defining it in the registry, adding it to the UI filter function, and updating route middleware. Existing routes can accept multiple scopes, so internal tools using the broad scope would continue to work.
+
+| Purpose | Path |
+|---------|------|
+| Enterprise API route registration | `api/src/api/enterprise/v1/index.ts` |
+| Enterprise room creation | `api/src/api/enterprise/v1/rooms/create-room.ts` |
+| Enterprise mural creation (blank) | `api/src/api/enterprise/v1/murals/create.ts` |
+| Template instantiation logic (shared) | `api/src/api/murals/create-from-template/index.ts` |
+| API key scope definitions | `api/src/api/common/api-key/scopes.ts` |
+| API key scope filtering (UI) | `api/src/api/companies/api-keys/index.ts` |
+| Template permissions | `api/src/api/can/entities/template.ts` |