feat(byok): add organization-wide key inheritance

[BillLeoutsakosvl346]

Summary

• Add encrypted organization-owned BYOK key pools managed from the existing BYOK settings page.
• Resolve provider credentials workspace-first, then inherit the current organization pool when the workspace has no local key for that provider.
• Restrict organization key management to organization owners/admins, enforce Enterprise entitlement for writes and runtime use, and retain delete access after downgrade.
• Show inherited provider status without exposing organization key metadata to workspace viewers.

Organization keys intentionally apply to executions in all current and future organization workspaces unless a workspace defines its own key for that provider. Existing provider fallback behavior remains unchanged when neither BYOK scope supplies a key.

Type of Change

• Bug fix
• New feature
• Breaking change
• Documentation
• Other: ___________

Testing

• Focused BYOK tests: 4 files, 51 tests
• Full @sim/app suite: 2,024 files and 27,612 tests
• App, database, and testing package type checks
• App lint and formatting
• Strict API validation: 1123/1123 routes
• React Query and package/client boundary audits
• Migration safety and Drizzle schema-drift checks
• git diff --check
• Manual workspace/organization scope, inheritance, override, downgrade, permission-loss, and error-state validation

Reviewers should focus on the workspace-first resolver boundary, organization authorization and downgrade behavior, and the intentionally organization-wide credential blast radius.

Checklist

• Code follows project style guidelines
• Self-reviewed my changes
• Tests added/updated and passing
• No new warnings introduced
• I confirm that I have read and agree to the terms outlined in the Contributor License Agreement (CLA)

Screenshots/Videos

Manual UI validation completed locally for both BYOK scopes, inherited badges, downgrade controls, and inherited-status failure handling.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
docs	Ready	Preview	Aug 19, 2026 2:08am

[cursor]

PR Summary

High Risk
Changes encrypted credential storage, resolution for all provider calls, and org-wide blast radius (keys apply to every workspace unless overridden). Auth, entitlement gating, and fail-closed behavior are heavily tested but remain security-critical.

Overview
Adds organization-scoped BYOK alongside workspace keys: encrypted pools in a new organization_byok_keys table, GET/POST/DELETE under /api/organizations/[id]/byok-keys, and a workspace inherited-status endpoint that returns provider IDs inherited from the org (no org key metadata to workspace viewers).

Runtime resolution in getBYOKKey is workspace-first; only when there is no workspace pool for a provider does it load org keys via the workspace’s organization, check Enterprise entitlement before decrypt, and round-robin the org pool. Workspace keys always win; corrupt workspace pools do not fall through to org keys.

The BYOK settings UI adds a workspace vs organization scope (?scope=) for hosted org admins, Inherited from organization badges, and per-action capabilities (add/update/delete) instead of a single read-only flag—including delete after Enterprise downgrade while blocking add/update.

Organization mutations require session principals, org admin/owner membership on the target org, and entitlement rules aligned with list/save/delete operations; audits and PostHog events cover org scope.

^{Reviewed by Cursor Bugbot for commit 9f8ff6e. Bugbot is set up for automated code reviews on this repo. Configure here.}

[gitguardian]

⚠️ GitGuardian has uncovered 5 secrets following the scan of your pull request.

Please consider investigating the findings and remediating the incidents. Failure to do so may lead to compromising the associated services or software components.

🔎 Detected hardcoded secrets in your pull request

GitGuardian id	GitGuardian status	Secret	Commit	Filename
36334842	Triggered	Generic High Entropy Secret	24859cb	apps/sim/lib/api-key/byok.test.ts	View secret
36334841	Triggered	Generic High Entropy Secret	24859cb	apps/sim/lib/api-key/byok.test.ts	View secret
36334842	Triggered	Generic High Entropy Secret	24859cb	apps/sim/lib/api-key/byok.test.ts	View secret
36334842	Triggered	Generic High Entropy Secret	24859cb	apps/sim/lib/api-key/byok.test.ts	View secret
36334842	Triggered	Generic High Entropy Secret	24859cb	apps/sim/lib/api-key/byok.test.ts	View secret

🛠 Guidelines to remediate hardcoded secrets

1. Understand the implications of revoking this secret by investigating where it is used in your code.
2. Replace and store your secrets safely. Learn here the best practices.
3. Revoke and rotate these secrets.
4. If possible, rewrite git history. Rewriting git history is not a trivial act. You might completely break other contributing developers' workflow and you risk accidentally deleting legitimate data.

To avoid such incidents in the future consider

• following these best practices for managing and storing secrets including API keys and other credentials
• install secret detection on pre-commit to catch secret before it leaves your machine and ease remediation.

---

^{🦉 GitGuardian detects secrets in your source code to help developers and security teams secure the modern development process. You are seeing this because you or someone else with access to this repository has authorized GitGuardian to scan your pull request.}

[greptile-apps]

Greptile Summary

The PR adds encrypted organization-owned BYOK pools, workspace-first credential inheritance, Enterprise entitlement enforcement, and organization-admin management controls.

• Adds organization BYOK persistence, API contracts, routes, authorization, auditing, and settings UI.
• Resolves workspace credentials first and inherits an entitled organization pool only when no workspace provider key exists.
• Exposes metadata-free inherited-provider status to workspace viewers and preserves deletion access after downgrade.
• Adds focused tests, migration metadata, query hooks, and API-validation coverage.

Confidence Score: 5/5

The PR appears safe to merge, with no concrete blocking or independently actionable non-blocking defects identified.

Workspace-first credential selection, organization authorization, Enterprise gating, downgrade cleanup, metadata isolation, and persistence changes form a consistent implementation with matching contracts and tests.

Important Files Changed

Filename	Overview
apps/sim/lib/api-key/byok.ts	Implements workspace-first resolution, organization inheritance, entitlement gating, rotation, and decrypt-failure handling without an accepted correctness issue.
apps/sim/lib/api-key/application/organization-byok-keys.ts	Adds admin-authorized organization key listing, creation, update, deletion, auditing, capacity enforcement, and inherited-status projection.
apps/sim/app/workspace/[workspaceId]/settings/components/byok/byok.tsx	Adds workspace/organization scope selection, inherited badges, entitlement-aware capabilities, and scope-specific mutations.
apps/sim/lib/api-key/byok-entitlement.ts	Centralizes hosted Enterprise entitlement checks for organization key writes and runtime inheritance.
apps/sim/lib/api/contracts/byok-keys.ts	Adds validated organization-key and inherited-status route contracts while preserving existing workspace contracts.
packages/db/schema.ts	Defines encrypted organization BYOK storage with organization and creator foreign keys plus provider lookup indexing.
packages/db/migrations/0292_free_multiple_man.sql	Adds the organization_byok_keys table and matching foreign keys and index consistently with the schema.
apps/sim/hooks/queries/byok-keys.ts	Adds organization and inherited-status queries with targeted cache invalidation after mutations.

Sequence Diagram

sequenceDiagram
  participant Exec as Workspace execution
  participant Resolver as BYOK resolver
  participant DB as PostgreSQL
  participant Billing as Enterprise entitlement
  participant Provider as Provider request
  Exec->>Resolver: Resolve provider key(workspaceId, providerId)
  Resolver->>DB: Read workspace provider pool
  alt Workspace pool exists
    DB-->>Resolver: Workspace ciphertexts
    Resolver->>Resolver: Rotate and decrypt workspace pool
  else No workspace pool
    Resolver->>DB: Read workspace organization and org pool
    DB-->>Resolver: Organization ciphertexts
    Resolver->>Billing: Check current Enterprise entitlement
    alt Entitled
      Resolver->>Resolver: Rotate and decrypt organization pool
    else Not entitled
      Resolver-->>Exec: No BYOK key
    end
  end
  Resolver-->>Exec: Effective key or null
  Exec->>Provider: Request using BYOK or existing fallback

Loading

_{Reviews (1): Last reviewed commit: "feat(byok): add organization scope to BY..." | Re-trigger Greptile}

[cursor]

Cursor Bugbot has reviewed your changes using high effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit fbee11d. Configure here.}

[BillLeoutsakosvl346]

The Org Admin can see this:

Everyone else can't even see this toggle.

For the admin, switched to "Organization" it looks like this:

For the rest, it looks like this: