user.onboarding

Onboards new users registered via Cognito

Onboards new users from Cognito into the platform.

Input fields (initial_data): cognito_sub, email, cognito_username, user_pool_ref, email_verified

States: initiated → pending_organization → completed initiated → completed (invitation fast-path) any → failed

Overview

Property	Value
Workflow type	Linear
Library	App-user
Version	1.0

Input Schema

Field	Type	Required	Default	Description
cognito_sub	string	No	—	Cognito user sub (UUID)
cognito_username	string	No	—	Cognito username
email	string	No	—	User email address
user_pool_ref	string	No	—	Cognito user pool reference
email_verified	string	No	—	Whether the email is verified (string 'true'/'false')

Output Schema

Field	Type	Required	Default	Description
cognito_sub	string	No	—	Cognito user sub
cognito_username	string	No	—	Cognito username
email	string	No	—	User email address
user_pool_ref	string	No	—	Cognito user pool reference
email_verified	string	No	—	Whether the email is verified
user_uuid	string	No	—	Platform user UUID
joined_via_invitation	boolean	No	—	Whether the user joined via invitation
joined_organizations	json	No	—	Organizations joined during onboarding
validated_at	string	No	—	ISO timestamp when user was validated
organization_uuid	string	No	—	UUID of the created or joined organization
organization_name	string	No	—	Name of the created organization
organization_domain	string	No	—	Domain of the created organization
completed_at	string	No	—	ISO timestamp when onboarding completed
failed_at	string	No	—	ISO timestamp when onboarding failed
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
initiated	Yes	No	—	validate_user	—
pending_organization	No	No	—	—	Waiting for user to create their first organization
completed	No	Yes	Yes	—	—
failed	No	Yes	No	—	—

State Diagram

Transitions

From	Action	To	Description
initiated	validate_user	pending_organization	—
initiated	complete_with_invitation	completed	—
pending_organization	create_organization	completed	—
* (any state)	fail	failed	—

API Usage

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

{
  "workflow_type": "user.onboarding",
  "initial_data": {
    "cognito_sub": "value",
    "cognito_username": "value",
    "email": "value",
    "user_pool_ref": "value"
  }
}