Mastering Runtime User Connections in Workato Embedded: The Complete Automation Playbook

If you're building on Workato's Embedded platform, you've probably encountered the concept of Runtime User Connections (RUC). It's a powerful feature that allows each of your end users to authenticate their own third-party accounts—like Dropbox, Salesforce, or Google Drive—while your recipes run under a shared customer workspace.

But here's the catch: while the documentation covers individual API calls well, the end-to-end orchestration—the sequencing, the pre-checks, and the edge cases—is where most partners get tripped up.

This article lays out the complete, production-ready flow: from onboarding a new customer to enabling per-user connections using the Embedded Auth Widget, complete with the decision logic that prevents broken states.

💡 The Use Case

Let's work with a concrete scenario throughout this article:

• You're an embedded partner building an integration platform for your customers. One use case allows end users to list files from their personal Dropbox accounts. Each user needs their own Dropbox connection—this is a classic Runtime User Connection use case.

Phase 1: Customer Onboarding (One-Time Setup)

Everything begins when the partner onboards a new customer onto the Workato Embedded platform. This is entirely backend-driven—no end-user interaction yet.

• Step 1 — Create the Customer Workspace

POST /api/managed_users
{
  "name": "Acme Corp",
  "external_id": "acme-001"
}        

• Step 2 — Import the Manifest via RLCM

The Recipe Lifecycle Management (RLCM) APIs let you push a pre-built package of recipes, connections, and dependencies into the customer workspace.

POST /api/managed_users/:managed_user_id/imports
{
  "manifest_id": "your-manifest-id"
}        

After this step, the customer workspace contains:

1. Shell connections (Dropbox + PartnerApp) — created but not authenticated.
2. Recipes — imported but not started.
3. Dependencies — lookup tables, properties, etc.

Phase 2: Default Connection & Recipe Start (The Missing Step)

This is the phase most partners overlook, and it's the most critical sequencing issue in the entire flow.

• ⚠️ Key Insight: A recipe cannot be started until its default (root) connections are authenticated. And if the recipe isn't running, no end user can trigger it—regardless of whether their runtime connection exists and is active.

Think of it this way: the recipe is the engine, the default connection is the ignition key, and the runtime user connection is the individual driver's seat adjustment. You need the engine running before any driver can use the car.

• Step 3 — Authenticate the Default Connection

The partner authenticates their side of the connection (e.g., PartnerApp). This can be done via the Workato UI, the Embedded Auth Widget, or programmatically via the Connections API:

PUT /api/managed_users/:id/connections/:connection_id
{
  "input": {
    "api_key": "partner-service-api-key"
  }
}        

• Step 4 — Start the Recipe

PUT /api/managed_users/:id/recipes/:recipe_id/start        

The recipe is now active and ready to serve end-user requests.

Phase 3: Runtime Connection Flow (Per End User)

Now comes the per-user experience. When User A opens your app and wants to connect their Dropbox, the Connection Orchestrator in your backend needs to run a decision tree.

• Step 5 — Pre-checks (Critical!)

Before presenting any auth UI to the end user, your backend must verify two things:

// 1. Is the recipe running?
GET /api/managed_users/:id/recipes/:recipe_id
// → Check: response.running === true

// 2. Is the default connection active?
GET /api/managed_users/:id/connections/:default_conn_id
// → Check: response.authorization_status === "success"        

If either check fails, do not show the auth widget. Instead, surface a user-friendly message like: "Integration setup is in progress. Please contact your administrator."

• Step 6 — Check for Existing Runtime Connection

GET /api/managed_users/:id/connections?runtime_user_id=user-a-external-id

// If found and authorized → skip to execution
// If found but unauthorized → show auth widget
// If not found → create shell, then show auth widget        

• Step 7 — Create Shell Runtime Connection (If Needed)

POST /api/managed_users/:id/connections

{
  "name": "Dropbox - User A",
  "provider": "dropbox",
  "runtime_user_id": "user-a-external-id",
  "parent_id": null  // Important: no parent for RUC
}        

• Step 8 — Render the Embedded Auth Widget

The widget is loaded as an iframe in your application, scoped to User A's shell connection. User A completes the Dropbox OAuth flow directly within your partner app.

<iframe
src="https://app.workato.com/direct_link/embedded/connections/:connection_id?workato_session_token=..."
  width="400" height="600"
/>        

Phase 4: Execution

With the recipe running, the default connection authenticated, and User A's runtime connection active—the circuit is complete.

When User A triggers the "list files" action, the Workato recipe engine resolves the connection: it sees that a runtime user connection exists for user-a-external-id and uses User A's credentials instead of the default connection. User A sees their files. User B sees theirs. Complete isolation.

⚠️ The Parent Connection Trap

• Critical Limitation: Parent connections are NOT supported for recipe functions toggled with runtime user connections. If you try to use a parent connection with RUC-enabled recipes, it fails and may cause unexpected behavior.

If your architecture uses callable recipe functions and those functions have RUC toggled on, you cannot rely on a parent connection cascading down. Each callable recipe function needs its own dedicated runtime user connection per user. Design your manifest and connection architecture accordingly!

✅ Production Checklist

Here's a quick reference for what your automation needs to handle:

• Customer Onboarding: Create workspace → RLCM import → Authenticate default connections → Start recipes.
• Per-User Flow: Verify recipe is running → Verify default connection → Check RUC existence → Create shell if needed → Auth Widget → Execute.
• Edge Cases: Handle expired RUCs (re-auth via widget) → Handle disconnected default connections → Handle recipe stopped states → Avoid parent connections for RUC recipe functions.

Closing Thoughts

Runtime User Connections unlock multi-tenant, per-user integrations at scale—but only when the orchestration is done right. The most common mistake partners make is jumping straight to the end-user auth widget without verifying that the foundational layer (default connections + running recipe) is in place.

Think of the flow as a three-layer cake: Customer Setup at the base, Recipe Activation in the middle, and User Connections on top. Skip a layer, and the whole thing collapses.

Build the pre-checks into your Connection Orchestrator, and you'll save yourself—and your end users—a lot of confusion.

#Workato #EmbeddedIntegrations #iPaaS #RuntimeConnections #IntegrationPlatform #SaaS #OEM #APIAutomation #B2BSaaS