# OpenWork Enterprise Activation Flow: Technical Implementation Guide

> Master the OpenWork enterprise activation flow with this technical guide. Learn how to implement the three-layer validation system for seamless desktop installations. Read now!

- Repository: [Different AI/openwork](https://github.com/different-ai/openwork)
- Tags: how-to-guide
- Published: 2026-08-16

---

**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`](https://github.com/different-ai/openwork/blob/main/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`](https://github.com/different-ai/openwork/blob/main/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`](https://github.com/different-ai/openwork/blob/main/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`](https://github.com/different-ai/openwork/blob/main/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`](https://github.com/different-ai/openwork/blob/main/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:

```tsx
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:

```ts
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:

```ts
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`](https://github.com/different-ai/openwork/blob/main/enterprise-activation-gate.tsx)**: React component that conditionally renders the activation page or workspace based on bootstrap state.
- **[`desktop-connect-grants.ts`](https://github.com/different-ai/openwork/blob/main/desktop-connect-grants.ts)**: Backend helper that constructs activation URLs and persists them to the desktop bootstrap.
- **[`enterprise-den-origin.ts`](https://github.com/different-ai/openwork/blob/main/enterprise-den-origin.ts)**: Server-side utility that extracts and validates the activation origin against the cloud MCP configuration.
- **[`install-config/src/index.ts`](https://github.com/different-ai/openwork/blob/main/install-config/src/index.ts)**: Zod schema defining `activationUrl` and `activationExpiresAt` fields used throughout the flow.
- **[`agent-context-diagnostics.ts`](https://github.com/different-ai/openwork/blob/main/agent-context-diagnostics.ts)** and **[`agent-context-cloud-probe.ts`](https://github.com/different-ai/openwork/blob/main/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`](https://github.com/different-ai/openwork/blob/main/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`](https://github.com/different-ai/openwork/blob/main/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`](https://github.com/different-ai/openwork/blob/main/packages/install-config/src/index.ts), which specifies the `activationUrl` string and `activationExpiresAt` ISO timestamp fields used throughout the desktop bootstrap and validation layers.