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 21, 2026 12:38am

[cursor]

PR Summary

High Risk
Touches encrypted provider credentials, org-wide inheritance into every workspace (including Pi sandboxes), and billing-gated access. A resolver or authz bug could leak or misuse organization API keys.

Overview
Organization admins can now store encrypted BYOK keys once for the whole org. Runs still prefer a workspace key per provider, then inherit the live org pool, then Sim-hosted keys.

Resolution (getBYOKKey) treats a nonempty workspace pool as exclusive — it never falls through to org keys if decrypt fails. Org keys are entitlement-gated before decrypt/rotation, round-robin across member workspaces, and tagged with scope in logs. Pi Create/Update PR and Plan still inject the resolved key (including inherited org keys) into the sandbox; Pi search still requires an explicit block key.

Management is session-only for org admins/owners. Writes need an active org plan (Pro/Max for Teams or Enterprise); list/delete remain after lapse. Workspace viewers only see inherited provider IDs, not org key metadata. The BYOK settings page adds Workspace/Organization scope, inherited badges, and granular add/update/delete capabilities.

Also adds organization_byok_keys, ORGANIZATION_PLAN_REQUIRED, resolveOrganizationPlan / checkOrgPlan, and documents the new providers, scopes, and Pi sandbox warning.

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

[gitguardian]

⚠️ GitGuardian has uncovered 2 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

🛠 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 with workspace-first credential resolution and plan-aware organization inheritance.

• Adds organization key management APIs, authorization, auditing, persistence, and settings UI.
• Extends model, embedding, and knowledge execution paths to inherit organization keys when no workspace override exists.
• Adds organization-plan entitlement handling, inherited-provider status, documentation, and focused tests.

Confidence Score: 5/5

The PR appears safe to merge because no blocking failure remains in the eligible follow-up review scope.

No blocking failure remains.

Important Files Changed

Filename	Overview
apps/sim/lib/api-key/byok.ts	Implements workspace-first credential selection and organization-level fallback while preserving existing provider fallback behavior.
apps/sim/lib/api-key/application/organization-byok-keys.ts	Adds authorized organization key listing, mutation, deletion, auditing, and inherited-status operations.
apps/sim/lib/api-key/byok-entitlement.ts	Adds fresh management-path and cached execution-path checks for organization-plan entitlement.
apps/sim/lib/billing/core/subscription.ts	Adds organization-plan resolution for plan-gated BYOK management and runtime use.
packages/db/schema.ts	Adds the organization BYOK key table definition corresponding to migration 0296.
packages/db/migrations/0296_organization_byok_keys.sql	Creates encrypted organization key storage with organization and creator foreign keys plus provider lookup indexing.
apps/sim/app/workspace/[workspaceId]/settings/components/byok/byok.tsx	Extends the BYOK settings surface with workspace and organization scopes and inherited-provider presentation.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
  Run[Workspace execution] --> Local{Workspace key exists<br/>for provider?}
  Local -->|Yes| WorkspaceKey[Use workspace key pool]
  Local -->|No| Org{Workspace belongs to<br/>an entitled organization?}
  Org -->|Yes| OrganizationKey[Use organization key pool]
  Org -->|No| ExistingFallback[Use existing hosted or explicit-key fallback]
  WorkspaceKey --> Provider[Call provider]
  OrganizationKey --> Provider
  ExistingFallback --> Provider

Loading

_{Reviews (4): Last reviewed commit: "fix(byok): keep an abandoned entitlement..." | Re-trigger Greptile}

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

[icecrasher321]

@greptile

[icecrasher321]

@greptile

[icecrasher321]

@greptile

[icecrasher321]

@cursor review

[cursor]

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

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