Skip to main content

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
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"
  }'
ParameterTypeDescription
namestringWorkspace name
branding_display_namestringShown on verification pages
branding_colorstringHex color for buttons/accents
branding_logo_urlstringLogo on verification pages
magic_link_expiryintSeconds. Default: 900
countriesstring[]Country codes
webhook_urlstringReceives all verification events
verification_modestringdismiss (default) or consent
verification_redirect_url_templatestringSupports {ticket_id}, {contact_id}, etc.
verification_redirect_delayintSeconds before redirect. Default: 4
verification_success_messagestringCustom 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

curl https://api.scute.io/v1/workspaces/{workspace_id}/children \
  -H "Authorization: Bearer {api_key}"
Returns { workspace_id, children: [...] }.

Get

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.
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

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

# 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

StatusMeaning
401Bad or missing API key
403Key doesn’t belong to this workspace
404Workspace or child not found
422Invalid params