# Enterprise Activation Flows in OpenWork: Implementation and Security Architecture

> Learn about OpenWork enterprise activation flows. Discover the three-layer system combining UI gates, desktop storage, and server validation for secure enterprise unlocks.

- Repository: [Different AI/openwork](https://github.com/different-ai/openwork)
- Tags: architecture
- Published: 2026-08-06

---

**OpenWork uses a three-layer activation system involving a client-side UI gate, desktop bootstrap storage, and server-side origin validation to securely unlock enterprise installations via one-time administrator-distributed links.**

The different-ai/openwork repository supports both cloud and enterprise distribution flavors, with the latter requiring a controlled activation mechanism. Enterprise activation flows in OpenWork ensure that only authorized users can access the workspace through a cryptographically secured redemption process that validates the activation origin against the configured cloud MCP endpoint.

## Three-Layer Activation Architecture

The enterprise activation system splits responsibilities across the client interface, desktop bootstrap configuration, and server-side validation layers.

### Client-Side UI Gate

The `EnterpriseActivationGate` component enforces the activation requirement before rendering the main workspace. Located in [`apps/app/src/react-app/domains/cloud/enterprise-activation-gate.tsx`](https://github.com/different-ai/openwork/blob/main/apps/app/src/react-app/domains/cloud/enterprise-activation-gate.tsx), this gate reads the desktop bootstrap configuration and checks `enterpriseActivationRequired()` to determine whether to display the activation page or the wrapped application children.

Once the `useEnterpriseActivationRequired()` hook detects a valid activation record in the bootstrap, the gate unlocks and renders the normal workspace interface.

### Desktop Bootstrap Storage

The activation record persists in the desktop bootstrap JSON, which stores the `activationUrl`, `activationExpiresAt` timestamp, and the Den origin reference. The Zod schema defining these fields lives in [`packages/install-config/src/index.ts`](https://github.com/different-ai/openwork/blob/main/packages/install-config/src/index.ts).

When an administrator redeems the activation URL, the desktop helper in [`ee/apps/den-api/src/desktop-connect-grants.ts`](https://github.com/different-ai/openwork/blob/main/ee/apps/den-api/src/desktop-connect-grants.ts) builds the activation link (`/activate?code=…`) and writes the record to the bootstrap configuration, including the timestamp when `activatedAt` was completed.

### Server-Side Origin Validation

Before allowing MCP (Model Context Protocol) calls, the server validates that the activation URL's origin matches the OpenWork Cloud MCP origin. The function `enterpriseDenOrigin` in [`apps/server/src/enterprise-den-origin.ts`](https://github.com/different-ai/openwork/blob/main/apps/server/src/enterprise-den-origin.ts) extracts the `enterpriseActivation` record, verifies that `activatedAt` exists, confirms the URL is a well-formed HTTPS origin, and returns the exact Den origin.

This prevents malicious activation URLs from unlocking the application. If origins diverge, diagnostics in [`agent-context-diagnostics.ts`](https://github.com/different-ai/openwork/blob/main/agent-context-diagnostics.ts) surface warnings advising administrators to add the origin to `OPENWORK_AGENT_DIAGNOSTICS_TRUSTED_ORIGINS`.

## Step-by-Step Activation Flow

The complete enterprise activation process follows five distinct stages:

1. **Installation** – When an enterprise admin installs the desktop, the Den backend returns an `activationUrl` and `activationExpiresAt` timestamp stored in the bootstrap configuration.

2. **Distribution** – The administrator shares the one-time link with end users through secure channels such as email or internal portals.

3. **Link Redemption** – The desktop application receives the request, validates the cryptographic code, writes the activation record into the bootstrap JSON, and records the `activatedAt` timestamp.

4. **UI Unlock** – The `useEnterpriseActivationRequired()` hook reads the updated bootstrap, verifies the activation record, and signals `EnterpriseActivationGate` to render the main workspace instead of the gated activation page.

5. **Runtime Security** – All subsequent MCP calls undergo origin verification. The system allows connections only if the stored activation origin matches `OPENWORK_CLOUD_MCP_ORIGIN`, blocking requests from unauthorized sources.

## Implementation Examples

Wrap the application root with the activation gate to enforce enterprise validation:

```tsx
// 1️⃣ Guard the whole app with the activation gate
import { EnterpriseActivationGate } from "./domains/cloud/enterprise-activation-gate";

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

```

Generate and persist activation URLs on the Den backend:

```ts
// 2️⃣ Generate an activation URL (run on the Den side)
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);
  // Store the URL/expiry in the desktop bootstrap JSON
  await writeBootstrap({
    enterpriseActivation: {
      activationUrl: activationUrl.toString(),
      activationExpiresAt: new Date(Date.now() + 15 * 60_000).toISOString(),
    },
  });
  return activationUrl.toString();
}

```

Validate activation origins server-side before processing MCP requests:

```ts
// 3️⃣ Server‑side origin validation (simplified)
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");
  // Compare with the configured cloud MCP origin
  if (origin !== process.env.OPENWORK_CLOUD_MCP_ORIGIN) {
    throw new Error("Activation origin does not match cloud MCP");
  }
  return true;
}

```

## Summary

- **EnterpriseActivationGate** in [`enterprise-activation-gate.tsx`](https://github.com/different-ai/openwork/blob/main/enterprise-activation-gate.tsx) controls UI access based on bootstrap activation state.
- **Activation records** containing `activationUrl` and `activationExpiresAt` persist in the desktop bootstrap JSON defined in [`install-config/src/index.ts`](https://github.com/different-ai/openwork/blob/main/install-config/src/index.ts).
- **One-time links** are generated in [`desktop-connect-grants.ts`](https://github.com/different-ai/openwork/blob/main/desktop-connect-grants.ts) and redeemed during the desktop installation process.
- **Origin validation** via `enterpriseDenOrigin` in [`enterprise-den-origin.ts`](https://github.com/different-ai/openwork/blob/main/enterprise-den-origin.ts) ensures MCP connections originate from trusted enterprise Den sources.
- **Diagnostic tools** help administrators troubleshoot origin mismatches by checking against `OPENWORK_CLOUD_MCP_ORIGIN`.

## Frequently Asked Questions

### What triggers the enterprise activation requirement in OpenWork?

The activation requirement triggers when the desktop bootstrap configuration contains an `enterpriseActivation` object with `activationUrl` and `activationExpiresAt` fields. The `EnterpriseActivationGate` component detects these fields via `enterpriseActivationRequired()` and renders the gated activation screen until the user redeems a valid activation link.

### How is the activation URL generated and secured?

The Den backend generates a cryptographically random UUID code in [`desktop-connect-grants.ts`](https://github.com/different-ai/openwork/blob/main/desktop-connect-grants.ts), constructs an HTTPS URL with the code as a query parameter, and stores the URL and expiration timestamp in the desktop bootstrap. The URL expires after a configured duration (default 15 minutes), and the server validates the origin against the enterprise tenant's allowed MCP origin before unlocking the application.

### What happens if the activation origin doesn't match the cloud MCP origin?

If the stored activation origin in the bootstrap diverges from `OPENWORK_CLOUD_MCP_ORIGIN`, the `enterpriseDenOrigin` validation fails and blocks MCP calls. The diagnostics layer in [`agent-context-diagnostics.ts`](https://github.com/different-ai/openwork/blob/main/agent-context-diagnostics.ts) surfaces a warning to the administrator, who must either correct the origin configuration or add the origin to the `OPENWORK_AGENT_DIAGNOSTICS_TRUSTED_ORIGINS` environment variable to establish trust.

### Where is the activation state persisted in an enterprise installation?

The activation state persists in the desktop bootstrap JSON file, defined by the Zod schema in [`packages/install-config/src/index.ts`](https://github.com/different-ai/openwork/blob/main/packages/install-config/src/index.ts). This file stores the `activationUrl`, `activationExpiresAt`, and `activatedAt` timestamp. The `EnterpriseActivationGate` reads this bootstrap configuration to determine whether to display the activation page or the main workspace.