> ## Documentation Index
> Fetch the complete documentation index at: https://docs.scute.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Child Workspaces

> Multi-tenant verification with isolated branding and credentials

# Child Workspaces

Provision isolated verification environments under your workspace. Each child gets its own app, API key, branding, and webhooks.

Auth: **parent workspace API key** in `Authorization: Bearer {key}`.

***

## Create

```
POST /v1/workspaces/{workspace_id}/children
```

```bash theme={null}
curl -X POST https://api.scute.io/v1/workspaces/{workspace_id}/children \
  -H "Authorization: Bearer {api_key}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corp",
    "branding_display_name": "Acme Corp",
    "branding_color": "#2563EB",
    "branding_logo_url": "https://acme.com/logo.png",
    "countries": ["us", "ca"],
    "magic_link_expiry": 900,
    "webhook_url": "https://your-server.com/webhooks/scute"
  }'
```

| Parameter                            | Type      | Description                                  |
| ------------------------------------ | --------- | -------------------------------------------- |
| `name`                               | string    | Workspace name                               |
| `branding_display_name`              | string    | Shown on verification pages                  |
| `branding_color`                     | string    | Hex color for buttons/accents                |
| `branding_logo_url`                  | string    | Logo on verification pages                   |
| `magic_link_expiry`                  | int       | Seconds. Default: 900                        |
| `countries`                          | string\[] | Country codes                                |
| `webhook_url`                        | string    | Receives all verification events             |
| `verification_mode`                  | string    | `dismiss` (default) or `consent`             |
| `verification_redirect_url_template` | string    | Supports `{ticket_id}`, `{contact_id}`, etc. |
| `verification_redirect_delay`        | int       | Seconds before redirect. Default: 4          |
| `verification_success_message`       | string    | Custom success text                          |

Response includes `app_id`, `api_key_token`, and `api_key_id`. Save the key — it's only returned once.

Scute auto-provisions: verify-only app, SMS provider, API key, and webhook endpoint (subscribed to all `verification.*` events).

***

## List

```bash theme={null}
curl https://api.scute.io/v1/workspaces/{workspace_id}/children \
  -H "Authorization: Bearer {api_key}"
```

Returns `{ workspace_id, children: [...] }`.

***

## Get

```bash theme={null}
curl https://api.scute.io/v1/workspaces/{workspace_id}/children/{child_id} \
  -H "Authorization: Bearer {api_key}"
```

Includes `api_key_token` and `webhook_endpoints` with secrets.

***

## Update

```
PATCH /v1/workspaces/{workspace_id}/children/{child_id}
```

Send only the fields you want to change. Branding syncs to the child's app automatically.

```bash theme={null}
curl -X PATCH https://api.scute.io/v1/workspaces/{workspace_id}/children/{child_id} \
  -H "Authorization: Bearer {api_key}" \
  -H "Content-Type: application/json" \
  -d '{ "branding_color": "#DC2626", "magic_link_expiry": 1800 }'
```

***

## Delete

```bash theme={null}
curl -X DELETE https://api.scute.io/v1/workspaces/{workspace_id}/children/{child_id} \
  -H "Authorization: Bearer {api_key}"
```

Returns `204 No Content`. Soft-delete.

***

## Full onboarding flow

```bash theme={null}
# 1. Create child
RESPONSE=$(curl -s -X POST https://api.scute.io/v1/workspaces/{workspace_id}/children \
  -H "Authorization: Bearer {parent_api_key}" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Acme Corp", "branding_display_name": "Acme Corp", "branding_color": "#2563EB", "webhook_url": "https://your-server.com/webhooks/acme" }')

CHILD_APP_ID=$(echo $RESPONSE | jq -r '.child_workspace.app_id')
CHILD_API_KEY=$(echo $RESPONSE | jq -r '.child_workspace.api_key_token')

# 2. Get M2M token
M2M_TOKEN=$(curl -s -X POST https://api.scute.io/v1/apps/${CHILD_APP_ID}/m2m/token \
  -H "Authorization: Bearer ${CHILD_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"client_name": "backend"}' | jq -r '.short_token')

# 3. Send verification
curl -X POST https://api.scute.io/v1/verify/${CHILD_APP_ID}/verifications/intent \
  -H "X-Authorization: Bearer ${M2M_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "intent_name": "Password Reset",
    "method": "sms",
    "verification_type": "magic_link",
    "meta_data": {
      "contact_email": "user@acme.com",
      "contact_phones": [{"phone_number": "+14155551234", "phone_type": "mobile"}],
      "ticket_id": "TICKET-001"
    }
  }'
```

The verification page shows the child's branding, not yours.

***

## Errors

| Status | Meaning                              |
| ------ | ------------------------------------ |
| 401    | Bad or missing API key               |
| 403    | Key doesn't belong to this workspace |
| 404    | Workspace or child not found         |
| 422    | Invalid params                       |