# Security Considerations for OpenWork Developers: Architecture, Implementation, and Best Practices

> OpenWork developers learn about security architecture and best practices. Explore defense-in-depth, RBAC permissions, CI/CD security gates, and more for secure implementation.

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

---

**OpenWork implements defense-in-depth through coordinated vulnerability reporting, bearer-token authentication with granular RBAC permissions like `security_configuration.manage`, mandatory re-authentication dialogs for sensitive actions, and automated security gates in CI/CD.**

OpenWork is a multi-tenant platform designed for desktop-first deployment with optional cloud hosting, requiring developers to understand its layered security model. Whether you are building integrations for the Den control plane or self-hosting internal instances, understanding the **security considerations for OpenWork developers** ensures you protect organizational data and maintain compliance. The platform enforces security through explicit permission contracts defined in `packages/docs/cloud/security-and-operations.mdx`, runtime verification dialogs, and infrastructure hardening rules specified in [`warden.toml`](https://github.com/different-ai/openwork/blob/main/warden.toml).

## Vulnerability Reporting and Coordinated Disclosure

Security researchers and developers must follow the coordinated disclosure policy outlined in [[`SECURITY.md`](https://github.com/different-ai/openwork/blob/main/SECURITY.md)](https://github.com/different-ai/openwork/blob/dev/SECURITY.md). The document directs vulnerability reports to a private email address and defines specific response SLAs for triage and remediation. This structured approach ensures that critical bugs are patched before public disclosure, protecting all downstream users of the OpenWork platform.

## Authentication and API Access Control

All Den control-plane endpoints enforce authentication through multiple schemes defined in [[`packages/docs/openapi.json`](https://github.com/different-ai/openwork/blob/main/packages/docs/openapi.json)](https://github.com/different-ai/openwork/blob/dev/packages/docs/openapi.json). The platform supports **bearer-token authentication** for user-authenticated routes, requiring the `Authorization: Bearer <session-token>` header. For organization-level API access, developers must include the **`x-api-key`** header. Additionally, SSO and SCIM integrations are guarded by the `security_configuration.manage` permission, ensuring that only authorized administrators can configure identity provider connections.

### Making Authenticated Requests to the Den API

When integrating with OpenWork APIs, always validate that your tokens belong to the appropriate security context:

```typescript
import { fetch } from 'undici';

// Replace with a real session token obtained via SSO login
const sessionToken = process.env.OPENWORK_SESSION_TOKEN!;

const res = await fetch('https://den.openworklabs.com/api/v1/organizations', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${sessionToken}`,
    'Accept': 'application/json',
  },
});

if (!res.ok) throw new Error(`HTTP ${res.status}`);
const orgs = await res.json();
console.log('Your orgs →', orgs);

```

This implementation uses the bearer-token flow described in the OpenAPI specification, ensuring proper session validation for every request.

## Role-Based Access Control (RBAC) Implementation

OpenWork implements fine-grained permissions through capability-based access control. The **`security_configuration.manage`** permission controls access to security settings, member management, team configuration, and resource allocation. Organization owners receive this capability by default, while administrators can be granted it through custom role assignments. This granular approach prevents privilege escalation by requiring explicit authorization for sensitive operations.

### Creating Organization API Keys

Generating API keys requires the `security_configuration.manage` capability, enforced at the endpoint level:

```typescript
import { fetch } from 'undici';

const adminToken = process.env.OPENWORK_ADMIN_TOKEN!; // must belong to a role with the permission

await fetch('https://den.openworklabs.com/api/v1/orgs/my-org/api-keys', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${adminToken}`,
    'Content-Type': 'application/json',
    'x-api-key': process.env.OPENWORK_ORG_API_KEY!, // optional if using org‑key auth
  },
  body: JSON.stringify({ name: 'ci‑pipeline-key' }),
});

```

Only users with the appropriate RBAC assignment can successfully invoke this endpoint, preventing unauthorized key generation.

## Runtime Security and Re-Authentication Controls

To prevent stale privileged actions, OpenWork implements **re-authentication dialogs** for sensitive UI operations. When users attempt actions like saving workspace settings or creating API keys, the platform surfaces a modal stating "For security, confirm it's you before changing workspace settings." This mechanism is driven by the `security` contract kind declared in [[`packages/enterprise-mcp-mock-server/src/contracts/runtime.ts`](https://github.com/different-ai/openwork/blob/main/packages/enterprise-mcp-mock-server/src/contracts/runtime.ts)](https://github.com/different-ai/openwork/blob/dev/packages/enterprise-mcp-mock-server/src/contracts/runtime.ts) and verified through end-to-end test flows.

### Implementing Security Re-Authentication in React

Developers building custom OpenWork interfaces should implement similar verification patterns:

```tsx
import { useState } from 'react';
import { Dialog } from '@/components/ui/dialog';

export function SensitiveActionButton() {
  const [showReauth, setShowReauth] = useState(false);

  const handleClick = async () => {
    // Attempt the privileged API call
    const ok = await attemptPrivilegedSave();
    if (!ok) setShowReauth(true); // backend responded with a security challenge
  };

  return (
    <>
      <button onClick={handleClick}>Save Workspace Settings</button>
      {showReauth && (
        <Dialog
          title="Security Check"
          description="For security, confirm it's you before changing workspace settings."
          onConfirm={async () => {
            await reauthenticate(); // e.g. open SSO popup
            setShowReauth(false);
            await attemptPrivilegedSave(); // retry after auth
          }}
        />
      )}
    </>
  );
}

```

This matches the "security" contract kind used throughout OpenWork's test flows, ensuring consistent protection against session hijacking.

## Deployment Hardening and Infrastructure Security

Self-hosting OpenWork requires specific security configurations to prevent common deployment vulnerabilities. The [`packages/docs/start-here/self-host.mdx`](https://github.com/different-ai/openwork/blob/dev/packages/docs/start-here/self-host.mdx) documentation highlights that Docker development stacks ship with a default `root:password` MySQL URL that must be replaced before production deployment. Additionally, Helm charts disable external breached-password lookups by default, requiring explicit security-team approval to enable them.

The repository includes a [`warden.toml`](https://github.com/different-ai/openwork/blob/main/warden.toml) file that enforces a **`diff-security-review`** gate on any pull request modifying security-relevant code. This prevents unauthorized changes to authentication logic or RBAC policies from reaching production without manual review.

## Secrets Management and Dependency Hygiene

OpenWork maintains strict **secret management** policies to prevent credential leakage. The `.env` files are never checked into version control, with a template provided in [`.env.example`](https://github.com/different-ai/openwork/blob/dev/.env.example) showing required environment variables without exposing actual secrets. The CI pipeline treats any accidental secret committed to the repository as a build failure, enforcing hygiene at the development stage.

For **dependency hygiene**, the [`pnpm-lock.yaml`](https://github.com/different-ai/openwork/blob/main/pnpm-lock.yaml) contains warnings about vulnerable transitive dependencies, such as historic CVEs in the `glob` package. Developers must review and upgrade these dependencies promptly to maintain a secure supply chain.

## Summary

- **Vulnerability reporting** follows coordinated disclosure via [`SECURITY.md`](https://github.com/different-ai/openwork/blob/main/SECURITY.md) with defined response SLAs.
- **Authentication** requires `Authorization: Bearer` tokens for user routes and `x-api-key` headers for organization access.
- **RBAC** uses capability-based permissions like `security_configuration.manage` to restrict sensitive operations.
- **Runtime security** enforces re-authentication dialogs through the `security` contract kind in [`runtime.ts`](https://github.com/different-ai/openwork/blob/main/runtime.ts).
- **Deployment hardening** requires replacing default Docker credentials and passing `diff-security-review` gates in [`warden.toml`](https://github.com/different-ai/openwork/blob/main/warden.toml).
- **Secret management** prohibits committing `.env` files and scans for accidental credential leakage in CI.
- **Dependency hygiene** tracks vulnerable packages through [`pnpm-lock.yaml`](https://github.com/different-ai/openwork/blob/main/pnpm-lock.yaml) alerts.

## Frequently Asked Questions

### What authentication methods does OpenWork support?

OpenWork supports **bearer-token authentication** for user sessions via the `Authorization: Bearer <token>` header and **API-key authentication** via the `x-api-key` header for organization-level access. The platform also integrates with SSO and SCIM providers, though configuring these requires the `security_configuration.manage` permission as defined in the OpenAPI specification.

### How does OpenWork enforce re-authentication for sensitive operations?

The platform implements **runtime re-authentication dialogs** that trigger when users attempt privileged actions like modifying workspace settings. These dialogs are enforced through the `security` contract kind defined in [`packages/enterprise-mcp-mock-server/src/contracts/runtime.ts`](https://github.com/different-ai/openwork/blob/main/packages/enterprise-mcp-mock-server/src/contracts/runtime.ts), requiring fresh verification before completing sensitive API calls.

### What is the purpose of the `security_configuration.manage` permission?

This **RBAC capability** grants users the authority to configure security settings, manage organization members and teams, allocate resources, and generate API keys. Organization owners possess this permission by default, while other administrators must be explicitly assigned custom roles containing this capability.

### How should developers handle security vulnerabilities found in OpenWork?

Developers must report vulnerabilities through the private disclosure process outlined in [`SECURITY.md`](https://github.com/different-ai/openwork/blob/main/SECURITY.md) rather than opening public issues. The security team maintains specific response timelines for triage and remediation. Additionally, developers should monitor [`pnpm-lock.yaml`](https://github.com/different-ai/openwork/blob/main/pnpm-lock.yaml) for CVE warnings and ensure [`warden.toml`](https://github.com/different-ai/openwork/blob/main/warden.toml) security gates pass before submitting PRs.