feat(byok): add organization-wide key inheritance

apps/docs/components/icons.tsx

@@ -5151,6 +5151,30 @@ export function BasetenIcon(props: SVGProps<SVGSVGElement>) {
   )
 }
 
+export function CohereIcon(props: SVGProps<SVGSVGElement>) {
+  return (
+    <svg {...props} height='1em' width='1em' viewBox='0 0 24 24' xmlns='http://www.w3.org/2000/svg'>
+      <title>Cohere</title>
+      <path
+        d='M8.128 14.099c.592 0 1.77-.033 3.398-.703 1.897-.781 5.672-2.2 8.395-3.656 1.905-1.018 2.74-2.366 2.74-4.18A4.56 4.56 0 0018.1 1H7.549A6.55 6.55 0 001 7.55c0 3.617 2.745 6.549 7.128 6.549z'
+        clipRule='evenodd'
+        fill='#39594D'
+        fillRule='evenodd'
+      />
+      <path
+        d='M9.912 18.61a4.387 4.387 0 012.705-4.052l3.323-1.38c3.361-1.394 7.06 1.076 7.06 4.715a5.104 5.104 0 01-5.105 5.104l-3.597-.001a4.386 4.386 0 01-4.386-4.387z'
+        clipRule='evenodd'
+        fill='#D18EE2'
+        fillRule='evenodd'
+      />
+      <path
+        d='M4.776 14.962A3.775 3.775 0 001 18.738v.489a3.776 3.776 0 007.551 0v-.49a3.775 3.775 0 00-3.775-3.775z'
+        fill='#FF7759'
+      />
+    </svg>
+  )
+}
+
 export function MondayIcon(props: SVGProps<SVGSVGElement>) {
   return (
     <svg

apps/docs/content/docs/en/platform/costs.mdx

@@ -215,34 +215,102 @@ Use your own API keys for supported providers instead of Sim's hosted keys to pa
 
 ### Supported Providers
 
-| Provider | Usage |
-|----------|-------|
-| OpenAI | Knowledge Base embeddings, Agent block |
-| Anthropic | Agent block |
-| Google | Agent block |
-| Mistral | Knowledge Base OCR, Agent block |
-| Fireworks | Agent block |
-| Firecrawl | Web scraping, crawling, search, and extraction |
-| Exa | AI-powered search and research |
-| Serper | Google search API |
-| Linkup | Web search and content retrieval |
-| Parallel AI | Web search, extraction, and deep research |
-| Perplexity | AI-powered chat and web search |
-| Jina AI | Web reading and search |
-| Google Cloud | Translate, Maps, PageSpeed, and Books APIs |
-| Brandfetch | Brand assets, logos, colors, and company info |
+The BYOK settings page groups providers the same way.
+
+<Tabs items={['Models', 'Search & web', 'Enrichment']}>
+  <Tab>
+    | Provider | Usage |
+    |----------|-------|
+    | OpenAI | LLM calls and Knowledge Base embeddings |
+    | Anthropic | LLM calls |
+    | Google | LLM calls |
+    | Mistral | LLM calls and Knowledge Base OCR |
+    | Z.ai | LLM calls |
+    | Cohere | Embeddings and Knowledge Base reranking |
+    | xAI | LLM calls |
+    | Kimi | LLM calls |
+    | Fireworks | LLM calls |
+    | Together AI | LLM calls |
+    | Baseten | LLM calls |
+    | Ollama Cloud | LLM calls |
+    | Fal.ai | Image and video generation |
+  </Tab>
+  <Tab>
+    | Provider | Usage |
+    |----------|-------|
+    | Firecrawl | Web scraping, crawling, search, and extraction |
+    | Exa | AI-powered search and research |
+    | Context.dev | Web scraping, crawling, search, and brand intelligence |
+    | Serper | Google search API |
+    | Linkup | Web search and content retrieval |
+    | Parallel AI | Web search, extraction, and deep research |
+    | Perplexity | AI-powered chat and web search |
+    | Jina AI | Web reading and search |
+    | Google Cloud | Translate, Maps, PageSpeed, and Books APIs |
+  </Tab>
+  <Tab>
+    | Provider | Usage |
+    |----------|-------|
+    | Brandfetch | Brand assets, logos, colors, and company info |
+    | Hunter | Email finder, verification, and domain search |
+    | People Data Labs | Person and company enrichment, search, and identity |
+    | Findymail | Email finder, verification, and phone lookup |
+    | Prospeo | Person and company enrichment and search |
+    | Wiza | Prospect search, individual reveal, and company enrichment |
+    | Datagma | Email, phone, person, and company enrichment |
+    | Dropcontact | GDPR-compliant contact enrichment and email finding |
+    | LeadMagic | Email finding, validation, and B2B profile enrichment |
+    | Icypeas | Email finding and verification |
+    | Enrow | Email finding and verification |
+    | ZeroBounce | Real-time email validation and deliverability checks |
+    | NeverBounce | Real-time email verification and list cleaning |
+    | MillionVerifier | Real-time email verification and deliverability checks |
+  </Tab>
+</Tabs>
+
+### Key scopes
+
+A key is stored at one of two scopes.
+
+| Scope | Applies to | Who can manage | Plan |
+|-------|------------|----------------|------|
+| **Workspace** | That workspace only | Workspace **admin** | Any plan on Sim Cloud |
+| **Organization** | Every current and future workspace in the organization | Organization **admin** or **owner** | Any organization plan on Sim Cloud — Pro for Teams, Max for Teams, or Enterprise |
+
+Organization keys let you set a provider key once instead of repeating it in every workspace. A new workspace added to the organization picks them up automatically.
+
+### Which key a run uses
+
+Precedence is resolved **per provider**, not per workspace:
+
+1. The workspace's own key for that provider, if it has one
+2. Otherwise, the organization's key for that provider
+3. Otherwise, Sim's hosted key, with the multiplier applied
+
+So a workspace that stores its own OpenAI key still inherits the organization's Anthropic key. A workspace key always wins over the organization key for the same provider — adding one is how you override inheritance for a single workspace.
+
+The BYOK settings page tags every provider your workspace is inheriting, so you can see which keys come from the organization before you override them.
 
 ### Setup
 
 1. Navigate to **Settings** → **BYOK** in your workspace
-2. Click **Add Key** for your provider
-3. Enter your API key and save
+2. Choose **Workspace** or **Organization** (organization admins only)
+3. Click **Add Key** for your provider
+4. Enter your API key and save
+
+You can store several keys per provider per scope. Requests are distributed evenly across the keys in whichever scope is in effect.
 
 <Callout type="info">
-  BYOK keys are encrypted at rest. Only workspace admins can manage keys.
+  BYOK keys are encrypted at rest and are never returned to the browser in full — the settings page only ever shows a masked value.
 </Callout>
 
-When configured, workflows use your key instead of Sim's hosted keys. If removed, workflows automatically fall back to hosted keys with the multiplier.
+<Callout type="warn">
+  The Pi block's **Create PR**, **Update PR**, and **Plan** modes run the model client inside a sandbox, so the resolved key — including an inherited organization key — is exposed to that sandbox. To keep an organization key out of it, give the workspace its own key for that provider. Pi's optional web search never falls back to a stored key; it always requires an explicit key on the block.
+</Callout>
+
+Deleting a workspace key makes that workspace fall back to the organization key if one exists, and to Sim's hosted keys otherwise. Deleting an organization key makes every workspace that was inheriting it fall back the same way.
+
+If your organization's plan lapses, organization keys stop applying and those workspaces fall back to Sim's hosted keys with the multiplier. The keys are retained, and organization admins can still delete them, but adding or updating them requires an active organization plan.
 
 ## Voice Input
 

apps/docs/openapi-v2-billing.json

@@ -452,7 +452,7 @@
                 "description": "Human-readable explanation of the error."
               },
               "details": {
-                "description": "Structured error details. On a `403` whose cause a caller can act on, this carries a `code` from a closed set:\n- `INSUFFICIENT_WORKSPACE_ROLE` — The caller has access to the workspace but its role is below the one this operation requires.\n- `PERSONAL_API_KEYS_DISABLED` — The workspace's organization does not allow personal API keys. Use a workspace API key.\n- `WORKSPACE_KEY_OPERATION_NOT_PERMITTED` — This operation is not available to a workspace-scoped API key. Use a personal API key.\n- `PRINCIPAL_KIND_NOT_PERMITTED` — This operation does not accept the caller’s kind of API key.\n- `ORGANIZATION_MEMBERSHIP_REQUIRED` — The caller is not a member of the organization it named.\n- `ORGANIZATION_ADMIN_REQUIRED` — The caller is a member of the organization but not an admin or owner.\n- `ENTERPRISE_PLAN_REQUIRED` — The organization has no active enterprise subscription.\n- `AUDIT_LOGS_DISABLED` — Audit logging is not enabled for this deployment.\n- `SKILL_EDITOR_ACCESS_REQUIRED` — The caller can write in the workspace but is not an editor of this skill.\n- `SECRET_ADMIN_ACCESS_REQUIRED` — The caller can write in the workspace but is not an admin of this secret. Ask a workspace admin, or someone holding admin on the secret, to grant access or set the value.\n- `WORKSPACE_RESOURCE_LIMIT_REACHED` — The workspace already holds the maximum number of resources of this kind. Delete one, or contact Sim to raise the limit; the message names the ceiling.\n- `PUBLIC_SHARING_NOT_ALLOWED` — The workspace's organization does not permit sharing this resource publicly. An organization admin controls the policy.\n- `CREDENTIAL_ADMIN_ACCESS_REQUIRED` — The caller can reach the workspace but cannot administer this credential.\n- `MCP_SERVER_URL_NOT_ALLOWED` — The supplied MCP server URL is outside the allowed domains or resolves to an internal address."
+                "description": "Structured error details. On a `403` whose cause a caller can act on, this carries a `code` from a closed set:\n- `INSUFFICIENT_WORKSPACE_ROLE` — The caller has access to the workspace but its role is below the one this operation requires.\n- `PERSONAL_API_KEYS_DISABLED` — The workspace's organization does not allow personal API keys. Use a workspace API key.\n- `WORKSPACE_KEY_OPERATION_NOT_PERMITTED` — This operation is not available to a workspace-scoped API key. Use a personal API key.\n- `PRINCIPAL_KIND_NOT_PERMITTED` — This operation does not accept the caller’s kind of API key.\n- `ORGANIZATION_MEMBERSHIP_REQUIRED` — The caller is not a member of the organization it named.\n- `ORGANIZATION_ADMIN_REQUIRED` — The caller is a member of the organization but not an admin or owner.\n- `ENTERPRISE_PLAN_REQUIRED` — The organization has no active enterprise subscription.\n- `ORGANIZATION_PLAN_REQUIRED` — The organization has no active organization subscription (Pro for Teams, Max for Teams, or Enterprise).\n- `AUDIT_LOGS_DISABLED` — Audit logging is not enabled for this deployment.\n- `SKILL_EDITOR_ACCESS_REQUIRED` — The caller can write in the workspace but is not an editor of this skill.\n- `SECRET_ADMIN_ACCESS_REQUIRED` — The caller can write in the workspace but is not an admin of this secret. Ask a workspace admin, or someone holding admin on the secret, to grant access or set the value.\n- `WORKSPACE_RESOURCE_LIMIT_REACHED` — The workspace already holds the maximum number of resources of this kind. Delete one, or contact Sim to raise the limit; the message names the ceiling.\n- `PUBLIC_SHARING_NOT_ALLOWED` — The workspace's organization does not permit sharing this resource publicly. An organization admin controls the policy.\n- `CREDENTIAL_ADMIN_ACCESS_REQUIRED` — The caller can reach the workspace but cannot administer this credential.\n- `MCP_SERVER_URL_NOT_ALLOWED` — The supplied MCP server URL is outside the allowed domains or resolves to an internal address."
               }
             },
             "required": ["code", "message"],

apps/docs/openapi-v2-files-audit.json

@@ -2297,7 +2297,7 @@
                 "description": "Human-readable explanation of the error."
               },
               "details": {
-                "description": "Structured error details. On a `403` whose cause a caller can act on, this carries a `code` from a closed set:\n- `INSUFFICIENT_WORKSPACE_ROLE` — The caller has access to the workspace but its role is below the one this operation requires.\n- `PERSONAL_API_KEYS_DISABLED` — The workspace's organization does not allow personal API keys. Use a workspace API key.\n- `WORKSPACE_KEY_OPERATION_NOT_PERMITTED` — This operation is not available to a workspace-scoped API key. Use a personal API key.\n- `PRINCIPAL_KIND_NOT_PERMITTED` — This operation does not accept the caller’s kind of API key.\n- `ORGANIZATION_MEMBERSHIP_REQUIRED` — The caller is not a member of the organization it named.\n- `ORGANIZATION_ADMIN_REQUIRED` — The caller is a member of the organization but not an admin or owner.\n- `ENTERPRISE_PLAN_REQUIRED` — The organization has no active enterprise subscription.\n- `AUDIT_LOGS_DISABLED` — Audit logging is not enabled for this deployment.\n- `SKILL_EDITOR_ACCESS_REQUIRED` — The caller can write in the workspace but is not an editor of this skill.\n- `SECRET_ADMIN_ACCESS_REQUIRED` — The caller can write in the workspace but is not an admin of this secret. Ask a workspace admin, or someone holding admin on the secret, to grant access or set the value.\n- `WORKSPACE_RESOURCE_LIMIT_REACHED` — The workspace already holds the maximum number of resources of this kind. Delete one, or contact Sim to raise the limit; the message names the ceiling.\n- `PUBLIC_SHARING_NOT_ALLOWED` — The workspace's organization does not permit sharing this resource publicly. An organization admin controls the policy.\n- `CREDENTIAL_ADMIN_ACCESS_REQUIRED` — The caller can reach the workspace but cannot administer this credential.\n- `MCP_SERVER_URL_NOT_ALLOWED` — The supplied MCP server URL is outside the allowed domains or resolves to an internal address."
+                "description": "Structured error details. On a `403` whose cause a caller can act on, this carries a `code` from a closed set:\n- `INSUFFICIENT_WORKSPACE_ROLE` — The caller has access to the workspace but its role is below the one this operation requires.\n- `PERSONAL_API_KEYS_DISABLED` — The workspace's organization does not allow personal API keys. Use a workspace API key.\n- `WORKSPACE_KEY_OPERATION_NOT_PERMITTED` — This operation is not available to a workspace-scoped API key. Use a personal API key.\n- `PRINCIPAL_KIND_NOT_PERMITTED` — This operation does not accept the caller’s kind of API key.\n- `ORGANIZATION_MEMBERSHIP_REQUIRED` — The caller is not a member of the organization it named.\n- `ORGANIZATION_ADMIN_REQUIRED` — The caller is a member of the organization but not an admin or owner.\n- `ENTERPRISE_PLAN_REQUIRED` — The organization has no active enterprise subscription.\n- `ORGANIZATION_PLAN_REQUIRED` — The organization has no active organization subscription (Pro for Teams, Max for Teams, or Enterprise).\n- `AUDIT_LOGS_DISABLED` — Audit logging is not enabled for this deployment.\n- `SKILL_EDITOR_ACCESS_REQUIRED` — The caller can write in the workspace but is not an editor of this skill.\n- `SECRET_ADMIN_ACCESS_REQUIRED` — The caller can write in the workspace but is not an admin of this secret. Ask a workspace admin, or someone holding admin on the secret, to grant access or set the value.\n- `WORKSPACE_RESOURCE_LIMIT_REACHED` — The workspace already holds the maximum number of resources of this kind. Delete one, or contact Sim to raise the limit; the message names the ceiling.\n- `PUBLIC_SHARING_NOT_ALLOWED` — The workspace's organization does not permit sharing this resource publicly. An organization admin controls the policy.\n- `CREDENTIAL_ADMIN_ACCESS_REQUIRED` — The caller can reach the workspace but cannot administer this credential.\n- `MCP_SERVER_URL_NOT_ALLOWED` — The supplied MCP server URL is outside the allowed domains or resolves to an internal address."
               }
             },
             "required": ["code", "message"],

apps/docs/openapi-v2-knowledge.json

@@ -3033,7 +3033,7 @@
                 "description": "Human-readable explanation of the error."
               },
               "details": {
-                "description": "Structured error details. On a `403` whose cause a caller can act on, this carries a `code` from a closed set:\n- `INSUFFICIENT_WORKSPACE_ROLE` — The caller has access to the workspace but its role is below the one this operation requires.\n- `PERSONAL_API_KEYS_DISABLED` — The workspace's organization does not allow personal API keys. Use a workspace API key.\n- `WORKSPACE_KEY_OPERATION_NOT_PERMITTED` — This operation is not available to a workspace-scoped API key. Use a personal API key.\n- `PRINCIPAL_KIND_NOT_PERMITTED` — This operation does not accept the caller’s kind of API key.\n- `ORGANIZATION_MEMBERSHIP_REQUIRED` — The caller is not a member of the organization it named.\n- `ORGANIZATION_ADMIN_REQUIRED` — The caller is a member of the organization but not an admin or owner.\n- `ENTERPRISE_PLAN_REQUIRED` — The organization has no active enterprise subscription.\n- `AUDIT_LOGS_DISABLED` — Audit logging is not enabled for this deployment.\n- `SKILL_EDITOR_ACCESS_REQUIRED` — The caller can write in the workspace but is not an editor of this skill.\n- `SECRET_ADMIN_ACCESS_REQUIRED` — The caller can write in the workspace but is not an admin of this secret. Ask a workspace admin, or someone holding admin on the secret, to grant access or set the value.\n- `WORKSPACE_RESOURCE_LIMIT_REACHED` — The workspace already holds the maximum number of resources of this kind. Delete one, or contact Sim to raise the limit; the message names the ceiling.\n- `PUBLIC_SHARING_NOT_ALLOWED` — The workspace's organization does not permit sharing this resource publicly. An organization admin controls the policy.\n- `CREDENTIAL_ADMIN_ACCESS_REQUIRED` — The caller can reach the workspace but cannot administer this credential.\n- `MCP_SERVER_URL_NOT_ALLOWED` — The supplied MCP server URL is outside the allowed domains or resolves to an internal address."
+                "description": "Structured error details. On a `403` whose cause a caller can act on, this carries a `code` from a closed set:\n- `INSUFFICIENT_WORKSPACE_ROLE` — The caller has access to the workspace but its role is below the one this operation requires.\n- `PERSONAL_API_KEYS_DISABLED` — The workspace's organization does not allow personal API keys. Use a workspace API key.\n- `WORKSPACE_KEY_OPERATION_NOT_PERMITTED` — This operation is not available to a workspace-scoped API key. Use a personal API key.\n- `PRINCIPAL_KIND_NOT_PERMITTED` — This operation does not accept the caller’s kind of API key.\n- `ORGANIZATION_MEMBERSHIP_REQUIRED` — The caller is not a member of the organization it named.\n- `ORGANIZATION_ADMIN_REQUIRED` — The caller is a member of the organization but not an admin or owner.\n- `ENTERPRISE_PLAN_REQUIRED` — The organization has no active enterprise subscription.\n- `ORGANIZATION_PLAN_REQUIRED` — The organization has no active organization subscription (Pro for Teams, Max for Teams, or Enterprise).\n- `AUDIT_LOGS_DISABLED` — Audit logging is not enabled for this deployment.\n- `SKILL_EDITOR_ACCESS_REQUIRED` — The caller can write in the workspace but is not an editor of this skill.\n- `SECRET_ADMIN_ACCESS_REQUIRED` — The caller can write in the workspace but is not an admin of this secret. Ask a workspace admin, or someone holding admin on the secret, to grant access or set the value.\n- `WORKSPACE_RESOURCE_LIMIT_REACHED` — The workspace already holds the maximum number of resources of this kind. Delete one, or contact Sim to raise the limit; the message names the ceiling.\n- `PUBLIC_SHARING_NOT_ALLOWED` — The workspace's organization does not permit sharing this resource publicly. An organization admin controls the policy.\n- `CREDENTIAL_ADMIN_ACCESS_REQUIRED` — The caller can reach the workspace but cannot administer this credential.\n- `MCP_SERVER_URL_NOT_ALLOWED` — The supplied MCP server URL is outside the allowed domains or resolves to an internal address."
               }
             },
             "required": ["code", "message"],