White-label setup

MIOSA can run behind your product and your customers’ domains. The important order is: set the organization identity first, then create workspaces/projects, then attach domains at the organization, workspace, project, deployment, or computer level.

Setup flow

1. Organization identity

Every account needs a real organization name. MIOSA derives the organization slug from that name, and the slug is permanent after setup. Do this before letting users create resources.

Example:

If a newly created account still has a temporary setup slug such as org-... or a slug that does not match the organization name, require setup before normal app navigation.

GET /api/v1/platform/tenants/current
Authorization: Bearer msk_live_...

If setup is required, update the tenant with the final organization name:

PUT /api/v1/tenants/{tenant_id}
Authorization: Bearer msk_live_...
Content-Type: application/json

{
  "name": "ClinicIQ"
}

The API normalizes the slug from name. If a slug is supplied, it must match the normalized organization name. After setup, name and slug are immutable.

2. Workspaces and projects

For white-label platforms, use workspaces for downstream customers and projects for the things they build.

ClinicIQ example:

Organization: ClinicIQ
  Workspace: Dr. Smith Clinic
    Project: Summer lead magnet
      Sandboxes: generated app previews
      Databases: form submissions
      Deployment: production lead magnet
      Domain: program.drsmithclinic.com
  Workspace: Downtown Dental
    Project: Booking portal

Create workspaces and projects directly, or let resource create calls auto-resolve them from workspace_slug / project_slug or external_workspace_id / external_project_id.

POST /api/v1/sandboxes
Content-Type: application/json

{
  "template_id": "miosa-sandbox",
  "workspace_slug": "dr-smith-clinic",
  "workspace_name": "Dr. Smith Clinic",
  "project_slug": "summer-lead-magnet",
  "project_name": "Summer Lead Magnet",
  "external_workspace_id": "clinic_123",
  "external_user_id": "dr-smith-456",
  "external_project_id": "project_789"
}

Responses include workspace_id and project_id. Store those IDs for future calls.

3. Default URL behavior

Until custom DNS is configured, MIOSA uses managed URLs:

For ClinicIQ, a deployment named Lead Magnet defaults to something like:

https://lead-magnet.cliniciq.miosa.app

This fallback is always available. Customers do not need to configure DNS unless they want their own domain.

4. Organization preview domain

Set a tenant preview domain when generated sandbox preview URLs should use your organization’s domain instead of miosa.app.

Example:

PUT /api/v1/tenant/preview-domain
Content-Type: application/json

{
  "preview_domain": "cliniciq.dev"
}

DNS:

After DNS propagates:

GET /api/v1/tenant/preview-domain/verify

Sandbox preview URLs then use:

https://5173-sbx01j9x.sandbox.cliniciq.dev

5. Workspace and project preview domains

Set a workspace preview domain when one downstream customer should get branded managed URLs for previews, computers, and deployments:

PUT /api/v1/workspaces/{workspace_id}/preview-domain
Content-Type: application/json

{
  "preview_domain": "drsmithclinic.com"
}

Set a project preview domain when only one generated thing should use its own base domain:

PUT /api/v1/projects/{project_id}/preview-domain
Content-Type: application/json

{
  "preview_domain": "program.drsmithclinic.com"
}

Each base domain uses the same two wildcard CNAME records: * and *.sandbox, both pointing to proxy.miosa.ai.

Examples after setup:

6. Resource custom domains

Attach exact domains when a project, deployment, or computer needs its own public URL.

Examples:

• drsmithclinic.com for a website deployment
• program.drsmithclinic.com for a lead magnet
• app.drsmithclinic.com for an app
• preview.drsmithclinic.com for a client-specific preview surface

For deployments:

POST /api/v1/deployments/{deployment_id}/domains
Content-Type: application/json

{
  "domain": "program.drsmithclinic.com"
}

For computers:

POST /api/v1/computers/{computer_id}/domains
Content-Type: application/json

{
  "domain": "desktop.drsmithclinic.com"
}

The domain response returns DNS instructions and verification status. Exact resource domains take precedence over managed MIOSA URLs.

7. Domain precedence

When MIOSA renders or routes a URL, use this mental model:

Workspace/project preview domains are inherited by generated sandbox previews, computer URLs, and managed deployment URLs. Exact resource custom domains still win when attached.

8. Branding

Tenant branding controls the product UI, desktop wallpaper, logos, support URL, and whether “Powered by MIOSA” is shown.

PUT /api/v1/tenant/branding
Content-Type: application/json

{
  "custom_app_name": "ClinicIQ",
  "custom_logo_url": "https://cliniciq.com/logo-dark.png",
  "support_url": "https://help.cliniciq.com",
  "desktop_wallpaper_url": "https://cliniciq.com/wallpaper.png",
  "powered_by_visible": false
}

Wallpaper requirements:

9. Browser tokens

Never expose an msk_* API key in a browser. Your backend creates sandboxes, deployments, and domains, then issues scoped browser tokens for the end user.

const token = await client.browserTokens.create({
  workspaceId: "550e8400-e29b-41d4-a716-446655440000",
  projectId: "660e8400-e29b-41d4-a716-446655440001",
  externalWorkspaceId: "clinic_123",
  externalUserId: "dr-smith-456",
  permissions: ["sandbox:read", "sandbox:exec", "preview:read"],
  ttlSeconds: 3600,
})

Complete setup checklist

• Require organization setup if the account still has a temporary slug or no organization name.
• Explain that organization name creates the permanent MIOSA slug one time.
• Create or auto-resolve workspaces for downstream customers.
• Create or auto-resolve projects for each app, website, lead magnet, document, or workflow.
• Store workspace_id and project_id from create responses.
• Use miosa.app fallback URLs until DNS is configured.
• Configure organization preview domain if previews should use your domain.
• Configure workspace or project preview domains when a customer/project needs its own managed URL base.
• Attach exact custom domains to deployments or computers when a customer wants their own URL.
• Apply tenant branding and support links.
• Issue browser tokens from your backend only.

See also