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

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.

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/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/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:

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:

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/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:

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 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 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 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 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 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.
• Deployment hardening requires replacing default Docker credentials and passing diff-security-review gates in 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 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, 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 rather than opening public issues. The security team maintains specific response timelines for triage and remediation. Additionally, developers should monitor pnpm-lock.yaml for CVE warnings and ensure warden.toml security gates pass before submitting PRs.

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