OpenWork Enterprise Activation Flow: Technical Implementation Guide

The OpenWork enterprise activation flow requires administrators to distribute one-time activation links that unlock desktop installations through a three-layer validation system involving UI gates, bootstrap configuration storage, and server-side origin verification.

The OpenWork platform supports both cloud and enterprise distribution flavors, with the latter requiring a secure activation mechanism to prevent unauthorized access. Unlike the cloud version, enterprise installations remain locked until an administrator distributes a unique activation URL to end users. This article examines the complete OpenWork enterprise activation flow as implemented in the different-ai/openwork repository, covering the client-side gates, desktop bootstrap persistence, and server-side validation layers.

Architecture of the Enterprise Activation System

The OpenWork enterprise activation flow operates across three distinct architectural layers that work sequentially to secure the installation.

Client-Side UI Layer

The EnterpriseActivationGate component in apps/app/src/react-app/domains/cloud/enterprise-activation-gate.tsx controls access to the workspace. This gate reads the desktop bootstrap configuration and checks enterpriseActivationRequired() to determine whether to display the activation page or render the wrapped children components. Until a valid activation record is persisted locally, users see a gated screen rather than the normal workspace interface.

Desktop Bootstrap Layer

The desktop bootstrap stores the activation record containing the activationUrl, activationExpiresAt timestamp, and a reference to the Den origin. Defined in packages/install-config/src/index.ts, this Zod schema is written when the activation URL is redeemed. The helper functions in ee/apps/den-api/src/desktop-connect-grants.ts construct the activation URL (/activate?code=…) and persist it in the bootstrap JSON, recording the timestamp when activation was completed.

Server-Side Validation Layer

Server-side security is enforced by enterpriseDenOrigin in apps/server/src/enterprise-den-origin.ts. This function extracts the enterpriseActivation record, verifies that activatedAt is present, validates the URL as a well-formed HTTPS origin, and ensures the origin matches the OpenWork Cloud MCP origin configured for the tenant. This prevents malicious URLs from unlocking the application by verifying the activation origin against the allowed cloud infrastructure.

Step-by-Step Activation Process

The complete OpenWork enterprise activation flow follows five distinct stages from installation to runtime security.

1. Installation: When an enterprise admin installs the desktop, the backend (Den) returns an activationUrl and activationExpiresAt expiration time.

2. Distribution: The administrator shares the one-time link with end users through secure channels like email or internal portals.

3. Link Redemption: When the user clicks the link, the desktop validates the code, writes the activation record into the bootstrap configuration, and records the activatedAt timestamp.

4. UI Unlocking: The useEnterpriseActivationRequired() hook reads the bootstrap; once verified, EnterpriseActivationGate stops rendering the gated page and displays the main workspace.

5. Runtime Security: All subsequent MCP calls require the stored activation origin to match the configured cloud MCP origin. The diagnostics layer in agent-context-diagnostics.ts surfaces mismatches and advises adding origins to OPENWORK_AGENT_DIAGNOSTICS_TRUSTED_ORIGINS.

Code Implementation Examples

Gating the Application

Wrap your main application component with the activation gate to enforce the enterprise check:

import { EnterpriseActivationGate } from "./domains/cloud/enterprise-activation-gate";

export default function App() {
  return (
    <EnterpriseActivationGate>
      <MainWorkspace />
    </EnterpriseActivationGate>
  );
}

Generating Activation URLs

On the Den backend, create one-time activation links with expiration:

import { readDesktopDistributionInfo } from "@/app/lib/desktop";

export async function createEnterpriseActivation(
  orgId: string,
  webUrl: string,
) {
  const code = crypto.randomUUID();
  const activationUrl = new URL("/activate", webUrl);
  activationUrl.searchParams.set("code", code);
  
  await writeBootstrap({
    enterpriseActivation: {
      activationUrl: activationUrl.toString(),
      activationExpiresAt: new Date(Date.now() + 15 * 60_000).toISOString(),
    },
  });
  
  return activationUrl.toString();
}

Validating Origins Server-Side

Verify the activation record against your cloud configuration to prevent origin spoofing:

import { exactEnterpriseOrigin } from "@/app/lib/enterprise-den-origin";

export function verifyActivationOrigin(bootstrap: any) {
  const origin = exactEnterpriseOrigin(bootstrap.enterpriseActivation);
  if (!origin) throw new Error("Invalid activation record");
  
  if (origin !== process.env.OPENWORK_CLOUD_MCP_ORIGIN) {
    throw new Error("Activation origin does not match cloud MCP");
  }
  
  return true;
}

Key Source Files

Understanding the enterprise activation flow requires familiarity with these critical files:

• enterprise-activation-gate.tsx: React component that conditionally renders the activation page or workspace based on bootstrap state.
• desktop-connect-grants.ts: Backend helper that constructs activation URLs and persists them to the desktop bootstrap.
• enterprise-den-origin.ts: Server-side utility that extracts and validates the activation origin against the cloud MCP configuration.
• install-config/src/index.ts: Zod schema defining activationUrl and activationExpiresAt fields used throughout the flow.
• agent-context-diagnostics.ts and agent-context-cloud-probe.ts: Diagnostic utilities that troubleshoot activation mismatches and origin validation failures.

Summary

• The OpenWork enterprise activation flow requires a one-time activation link distributed by administrators to unlock installations.
• EnterpriseActivationGate in enterprise-activation-gate.tsx controls UI access based on bootstrap configuration.
• The desktop bootstrap stores activation metadata including activationUrl, expiration timestamps, and Den origin references in the schema defined in install-config/src/index.ts.
• Server-side validation via enterpriseDenOrigin prevents malicious URLs by verifying HTTPS origins against the configured cloud MCP.
• Diagnostic tools help administrators troubleshoot origin mismatches through OPENWORK_AGENT_DIAGNOSTICS_TRUSTED_ORIGINS.

Frequently Asked Questions

How does the EnterpriseActivationGate component determine when to show the activation page?

The component reads the desktop bootstrap configuration and calls enterpriseActivationRequired() to check for the presence of a valid enterpriseActivation record. If the record is missing or expired, it renders the activation page; otherwise, it displays the wrapped child components representing the main workspace.

What happens if the activation URL expires before the user clicks it?

The activationExpiresAt field stored in the bootstrap configuration enforces expiration. If the current time exceeds this timestamp, the activation record is considered invalid, and the user must request a new activation link from the administrator. The desktop bootstrap requires rewriting with fresh credentials from the Den backend.

How does OpenWork prevent malicious activation URLs from unlocking enterprise installations?

The server-side enterpriseDenOrigin function validates that the stored activation URL is a well-formed HTTPS origin and matches the OPENWORK_CLOUD_MCP_ORIGIN environment variable configured for the tenant. If origins diverge, the application throws validation errors and diagnostic tools advise adding trusted origins to OPENWORK_AGENT_DIAGNOSTICS_TRUSTED_ORIGINS.

Where is the activation record schema defined in the OpenWork codebase?

The Zod schema defining the activation record structure lives in packages/install-config/src/index.ts, which specifies the activationUrl string and activationExpiresAt ISO timestamp fields used throughout the desktop bootstrap and validation layers.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}