---
title: "Provision a customer workspace in one step"
method: POST
path: "/v1/admin/workspaces/provision"
tags: ["Instance admin"]
---

# Provision a customer workspace in one step

`POST /v1/admin/workspaces/provision`

## Request

- Base URL: `https://shareout.site`
- URL: `https://shareout.site/v1/admin/workspaces/provision`
- Auth: HTTP bearer

Instance admins only (session, or a personal `so_` token — workspace Agent `sot_` tokens are refused; a workspace owner/admin gets 403). Creates the workspace (or adopts the one on `slug`), applies branding, policy defaults and feature flags, creates starter folders, invites the admins with the normal invite email, and stores connectors through the normal encrypted connector path. Idempotent by `slug`: a re-run fills in what is missing and reports the rest `unchanged` — no second workspace, folder, membership or connector, no resent live invite, no overwritten credential. A failing step is reported in `steps` and the run continues (HTTP 207). Credential values are never returned or audited. Every step writes a `workspace.provision.*` audit row.

## Request body

- object
  - `name` string, required
  - `slug` string, required: Also the subdomain. 2–63 lowercase letters, digits, hyphens; reserved names (www, api, admin, …) refused.
  - `locale` 'en' | 'es'
  - `description` string
  - `owner_email` string: Owner of a new workspace. Defaults to the first of `admins`; ignored when the workspace exists.
  - `admins` string[], required
  - `if_exists` 'match' | 'update' | 'fail': `match` adopts an existing slug only when its name matches; `update` adopts it and renames; `fail` refuses.
  - `subdomain` boolean
  - `branding` object
    - `accent_color` string
    - `hide_footer` boolean
    - `logo` union: An https URL (fetched by the instance), or bytes. PNG/JPG/WEBP/SVG, max 512 KB.
      - string, uri
      - object
        - `url` string, uri
      - object
        - `data_base64` string, required
        - `content_type` string, required
  - `policy` object
    - `allowed_domains` string[]
    - `allowed_emails` string[]
    - `external_sharing` boolean: The `collab.external_sharing` flag.
    - `guest_comments` boolean: Guest comments on the folders this run creates.
    - `knowledge` boolean
    - `features` object: Feature-flag overrides, keys from the feature registry.
  - `folders` string[]
  - `connectors` object[]: Same body as `POST /v1/workspaces/{workspaceId}/connections`. An existing connector with the name is left untouched.
  - `resend_invites` boolean
  - `templates` string: Template set to install. `pending` until the instance has templates.
  - `custom_domain` string: Hostname to attach. `pending` until the instance has custom domains.

## Response `200`

Existing workspace, nothing failed

- ProvisionSummary
  - `ok` boolean
  - `created` boolean
  - `workspace` object
    - `id` string
    - `name` string
    - `slug` string
    - `locale` string
  - `links` object
    - `home` string
    - `admin` string
    - `subdomain` string, nullable
    - `instance_admin` string
  - `admins` object[]
    - `email` string
    - `role` 'owner' | 'admin' | 'member'
    - `status` 'invited' | 'already_invited' | 'active' | 'added' | 'failed'
    - `email_sent` boolean
    - `invite_url` string: Only when the invite email did not go out.
    - `error` string
  - `steps` object[]
    - `step` string: workspace, branding, policy, folders, admins, connector:<name>, templates, custom_domain
    - `status` 'created' | 'updated' | 'unchanged' | 'skipped' | 'pending' | 'failed'
    - `detail` object
    - `error` string
    - `next_step` string
  - `next_steps` string[]
  - `duration_ms` integer

## Other responses

- `201`: Workspace created, nothing failed
- `207`: Workspace exists; at least one step failed (see `steps` and `next_steps`). Fix and re-run.
- `400`: Invalid request
- `403`: Access denied
- `409`: Slug taken or version conflict

## Changes

- **2026-10-17** `a43d748cfdda`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/shareout/apis/shareout-rest-api/changes/v1/admin/workspaces/provision/post.md)

---

[API](https://skmtc.dev/shareout/apis/shareout-rest-api.md) - [All operations](https://skmtc.dev/shareout/apis/shareout-rest-api/llms.txt) - [OpenAPI document](https://skmtc.dev/shareout/apis/shareout-rest-api/revisions/1e3f7fd34f6d?raw)