apphost.site.claim

Claim <slug>.app.orkestia.dev for a provisioned, live-mode identity app: enforce subscription + identity-app preconditions, validate slug uniqueness and the per-org site quota, then create the hosted_site row (mode=active, no release yet). Idempotent per identity app; slug is immutable after claim.

Claim a hosted-site slug (creates the hosted_site row; DB-only).

Overview

Property	Value
Workflow type	Atomic
Library	App-apphost
Version	1.0

Input Schema

Field	Type	Required	Default	Description
identity_app_uuid	uuid	Yes	—	UUID of the IdentityApp this site authenticates against. Must be provisioned (client exists) and NOT in dev mode.
slug	string	No	—	Requested subdomain label (^[a-z][a-z0-9-]{2,39}$). Omitted: derived from the identity app name. Immutable after claim.

Output Schema

Field	Type	Required	Default	Description
site_uuid	uuid	Yes	—	UUID of the created (or existing) hosted_site row.
slug	string	Yes	—	Claimed subdomain label.
url	string	Yes	—	Public serving URL: https://<slug>.app.orkestia.dev.
organization_uuid	uuid	No	—	Owning organization (derived from the identity app).
identity_app_uuid	uuid	No	—	—
mode	string	No	—	Serving mode: active
created	boolean	Yes	—	True when this run inserted a new hosted_site row.
already_exists	boolean	Yes	—	True when the identity app already had a hosted_site (idempotent return).
failure_reason	string	No	—	—
failure_type	string	No	—	—
failed_action	string	No	—	—
failed_at_state	string	No	—	—
failed_step	string	No	—	—
failed_layer	string	No	—	—
error	string	No	—	—
error_type	string	No	—	—

States

State	Initial	Terminal	Success	Auto-advance	Description
pending	Yes	No	—	execute	Claim accepted; will validate preconditions and create the site
completed	No	Yes	Yes	—	Site claimed (or already existed)
failed	No	Yes	No	—	Claim rejected; failure_reason carries the precondition that failed

State Diagram

Transitions

From	Action	To	Description
pending	execute	completed	—
* (any state)	fail	failed	—

Outcomes

Outcome	Type	Description	State Data Keys
claimed	SUCCESS	Hosted site slug claimed (or existing claim returned)	site_uuid, slug, url
failed	FAILURE	Apphost workflow failed	failure_reason

API Usage

POST /api/workflows/start
Content-Type: application/json

{
  "workflow_type": "apphost.site.claim",
  "initial_data": {
    "identity_app_uuid": "value"
  }
}