Platform / White-label

This section is for builders — platforms that embed MIOSA so their customers can build, preview, and deploy apps inside the builder’s own product (AI app builders, white-label SaaS).

If you’re a developer using MIOSA to ship your own app, read Quickstart Track A instead.

What is the white-label model?

MIOSA lets one organization act as a platform for many downstream customers without giving those customers MIOSA accounts. Your backend holds a server-side msk_* key and creates resources inside MIOSA workspaces and projects. External attribution fields are still accepted for mapping back to your own database, but canonical ownership is now MIOSA workspace_id and project_id.

This is the ClinicIQ pattern: ClinicIQ is a SaaS that lets dental clinics build marketing sites, booking apps, lead magnets, and documents. ClinicIQ has one MIOSA organization slug, for example cliniciq. Each client clinic can be a MIOSA workspace, each site/app/document can be a project, and every sandbox, computer, database, deployment, storage bucket, volume, function, job, and domain belongs to that project.

The tenant hierarchy is:


MIOSA Organization (ClinicIQ / slug: cliniciq)
  └── MIOSA API key (msk_cliniciq_server_prod)
       └── Workspace (Dr. Smith Clinic / slug: dr-smith-clinic)
            └── Project (Lead Magnet / slug: lead-magnet)
                 └── Sandboxes, Computers, Databases, Deployments, Domains

When to use it

You are building a no-code / low-code platform and end users build inside your product
Your customers must never need a MIOSA account or API key
You need per-customer usage metering and chargeback on a single MIOSA bill
Browser-side preview iframes must not expose your server-side API key
You want to group sandboxes, computers, deployments, databases, and domains by workspace and project

Quick example

How it fits together

The msk_* key never reaches the browser. The browser only receives a short-lived preview token scoped to a single resource.

Ownership and attribution fields

Every create request accepts canonical ownership fields and optional external attribution fields:

Field	Type	Purpose
`workspace_id`	UUID	Existing MIOSA workspace that owns the resource
`workspace_slug`	string	Existing or auto-created workspace slug
`workspace_name`	string	Display name used if a workspace is auto-created from an external ID
`project_id`	UUID	Existing MIOSA project that owns the resource
`project_slug`	string	Existing or auto-created project slug inside the workspace
`project_name`	string	Display name used if a project is auto-created
`external_workspace_id`	string	Your customer’s account, clinic, tenant, or workspace ID
`external_user_id`	string	The individual end user who triggered the action
`external_project_id`	string	Your project/app/document ID

If you pass an external workspace or project ID without a MIOSA ID/slug, MIOSA resolves or creates the matching workspace/project for the authenticated organization. Responses include both canonical IDs and external IDs so your backend can store the MIOSA IDs and use them on future calls.

These IDs are scoped under your organization. Another MIOSA organization cannot read or mutate your resources even if they know the same slug or external ID values.

The one server-side key. Rotation, scopes, audit. Open →

Canonical workspace_id / project_id ownership plus external_* fields for billing and your own database. Open →

Short-lived scoped tokens for preview and terminal access from the end-user’s browser. Open →

Per-tenant, per-external-workspace usage. Chargeback to your customers. Open →

Reference integration

A working end-to-end example lives at examples/white-label-cliniciq/. It shows server-side sandbox creation with attribution, tenant-scoped listing, preview token minting, and browser-safe embedding in ~150 lines of TypeScript.

See also examples/agent-builds-static-app/ for the “AI agent builds + previews + deploys” pattern.