Self-Service Start Links

Last Updated: January 1, 2026

The Self-Service Start Link (or "Start Link") is a powerful feature that provides a public, shareable URL allowing anyone—including users outside the workspace—to initiate a new session of a workflow. This is the primary mechanism for distributing workflows to external participants like customers, clients, or partners.

---

Core Concepts

The feature is built around two main database tables that work together to configure a public link and define how new sessions are created from it.

Database Tables

self_service_starts table

• Links a workflow_id to a unique, shareable UUID
• Acts as the master configuration for a specific start link
• Tracks usage analytics

self_service_assignments table

• Pre-assigns users or roles for any session created via a specific self-service link
• Allows builders to define who will be assigned to each role when a new session begins

The "Self-Service User" Role

This is not a formal role but a special assignment type within the self_service_assignments table, indicated by the is_customer: true flag. It designates a role that will be automatically assigned to the user who clicks the start link and initiates the session.

---

End-to-End Flow

1. Configuration (The Builder's Experience)

UI Entry Point: The process begins in the ManageStartLinksModal.tsx component, opened from the workflow builder.

Creation Steps:

1. Builder clicks "Create New Start Link" (only enabled if workflow is published)
2. Can optionally enable "Limit to one session per user" to prevent duplicate submissions
3. System creates a new record in self_service_starts with a unique UUID
4. Builder configures role assignments:
   • Internal User: Select a specific workspace member from dropdown
   • External User: Select "Self-service user" option (sets is_customer: true)

2. The Public Start Page (The End-User's Experience)

Route: /start/[selfServiceStartId]

Flow:

1. User navigates to the public URL
2. Page displays workflow name, description, and branding (server-rendered)
3. If not logged in, user is prompted to "Login or Sign Up to Continue"
4. Once authenticated, system checks for resumable sessions
5. User can either "Continue Existing Session" or "Start New Session"

3. Session Creation (The Backend)

API Endpoint: POST /api/workflow_runs/[workflowId]/self_service_start

Process:

1. Validates user is authenticated and workflow is published
2. Creates new workflow_run record
3. Increments uses count on the self_service_starts record
4. Creates session_role_assignments based on pre-configured assignments
5. Creates initial session_assignments for starting stages
6. Adds user to workspace as guest if not already a member
7. Sends notifications to all assigned users
8. Redirects user to the new session

---

Link Lifecycle and Workflow Versioning

A Start Link is directly tied to the specific workflow version it was created for.

When a New Workflow Version is Published

1. Automatic Archiving: All Start Links belonging to the previous version are automatically archived
2. Starting New Sessions is Disabled: Archived links can no longer initiate new sessions
3. Resuming Existing Sessions is Preserved: Users can still find and resume their in-progress work

This ensures new sessions always use the latest workflow version while preserving access to in-flight work.

---

Key Files & Endpoints

Frontend

• Public Page: app/pages/start/[selfServiceStartId].tsx
• Configuration UI: app/components/ManageStartLinksModal.tsx

API Endpoints

• POST /api/workflow_runs/[workflowId]/self_service_start - Create session
• POST /api/self_service_starts/create - Create link
• POST /api/self_service_starts/delete - Archive link
• POST /api/self_service_starts/index - List links
• POST /api/self_service_assignments/create - Create assignment
• POST /api/self_service_assignments/delete - Delete assignment
• POST /api/self_service_assignments/index - List assignments

Database Tables

• self_service_starts
• self_service_assignments
• workflow_runs (stores reference to self_service_start_id)

---

Current Capabilities

One Session Per User

Enable the "Limit to one session per user" option to restrict each authenticated user to creating only one session from a specific Start Link. This is critical for preventing duplicate submissions in use cases like:

• Formal applications
• Surveys
• Certification tests

Note: This setting cannot be changed after the link is created.

Resumable Sessions

The system automatically detects if a user has an existing session from a specific link and offers them the option to continue rather than creating a duplicate.

Guest User Management

External users are automatically added to the workspace with a guest role, granting them the necessary permissions to participate in their assigned session without requiring manual intervention.

---

Future Enhancements

Singleton Session Links (Collaborative Join)

Configure a Start Link so that every user who clicks it joins the same, single session, rather than creating a new one each time.

Use Case: A single link sent to a client team where each member joins the same project onboarding session as a participant.

Pre-filled Data via URL Parameters

Pass data directly into a new session via the URL, pre-populating blocks and sheet columns.

Example: /start/[id]?name=Acme%20Inc&contact_email=test@acme.com

Domain-Restricted Links

Restrict link usage to users with email addresses from specific domains.

Use Case: Share a workflow with a partner organization, allowing only @acme.com email addresses.

Password-Protected Links

Add a simple password requirement before users can start a session.

Invite-Only Links (Allow-list)

Restrict a Start Link to a specific, predefined list of users by email address.

Link Expiration & Usage Limits

Add the following columns to self_service_starts:

• name or label - Distinguish between multiple links
• expires_at - Automatically disable links after a date
• max_uses - Disable after a specific number of uses

Webhook Integrations

Trigger webhooks upon successful session creation to integrate with external systems like CRMs.

Link-Specific Analytics

Track detailed metrics for each link:

• Views vs. Starts (conversion rate)
• Completion rate
• Session list
• Cohort analysis

---

Architectural Observations

Strengths

1. Clean Separation of Concerns: Configuration UI, public page, and backend logic are well-separated
2. Excellent UX: Server-rendered pages, resumable sessions, and automatic guest management
3. Effective Guest Management: Automatic workspace membership with appropriate permissions

Suggested Improvements

1. Transactional Integrity: Wrap all database operations in a single transaction
2. Rate Limiting: Prevent abuse on the public endpoint
3. Enhanced Settings: Add link names, expiration dates, and usage limits
4. Permission Documentation: Clearly define guest role capabilities
5. Error Handling: Provide user-friendly messages for expired or invalid links

---

Related Documentation