feat(credentials): add named API keys to credential groups

Author: TheodoreSpeaks

apps/docs/content/docs/platform/connected-accounts.mdx

@@ -57,7 +57,7 @@ For Search-enabled organizations, open **Settings → Integrations → People**.
 
 Invitees can contribute accounts without joining your organization. The invitation grants access to their connection form; it does not grant access to your workspaces or workflows.
 
-Use the invitation email in workflow lookups. For example, if you invite `alex@example.com`, **Find Organization Account** with that email and **Gmail** finds Alex's active Gmail contribution.
+Use the invitation email in workflow lookups. For example, if you invite `alex@example.com`, **Find Credential Group Account** with that email and **Gmail** finds Alex's active Gmail contribution.
 
 #### How the email is associated with a Sim user
 
@@ -83,17 +83,25 @@ Removing a workspace stops subsequent use of the pool. It does not recall provid
 
 Use the **Credential** block's organization operations in an allowed workspace:
 
-- **Find Organization Account** selects an OAuth account by invitation email and provider.
-- **List Organization Accounts** returns a page of OAuth accounts, optionally filtered by email and providers.
-- **Find Organization MCP Connection** selects a person's managed MCP connection by invitation email and MCP provider.
-- **List Organization MCP Connections** returns a page of managed MCP connections, optionally filtered by email and provider.
+- **Find Credential Group Account** selects an OAuth account by invitation email and provider.
+- **List Credential Group Accounts** returns a page of OAuth accounts, optionally filtered by email and providers.
+- **Find Credential Group MCP Connection** selects a person's managed MCP connection by invitation email and MCP provider.
+- **List Credential Group MCP Connections** returns a page of managed MCP connections, optionally filtered by email and provider.
 
 The organization is determined by the workflow's workspace. You do not enter a credential group ID or organization ID in the block.
 
 The outputs are account references, without tokens. Use an OAuth `credentialId` in the corresponding integration block's credential field. For managed MCP, `credentialId` identifies the person's connection; `mcpServerId` identifies shared configuration and cannot select that person's authorization by itself.
 
 See the [Credential block reference](/workflows/blocks/credential#organization-accounts) for inputs, outputs, pagination, and connection-event triggers.
 
+## Named API keys
+
+In the Credential Group's **Integrations** tab, select **Add API key**. Enter a name and an optional description explaining where invitees can get the key. The administrator defines the request; each invited person enters their own secret value in the connection form. A name such as `EXA_API_KEY` is permitted but does not create an environment variable.
+
+Allow **API keys** for the workspaces that should use these contributions. In a workflow, **List Credential Group API Keys** returns submitted key IDs and metadata. Pass a selected ID into **Get Credential Group API Key**, then reference its `apiKey` output directly in the downstream block. See the [named API key example](/workflows/blocks/credential#named-api-keys).
+
+People can replace or disconnect their key from their connection form. Renaming a request preserves the submissions and IDs. Removing a request deletes every submitted key for that request. Names and connection status are visible in management views; saved values are not returned to those views.
+
 ## Reconnect or stop sharing
 
 People can open **Settings → Account → Connected accounts** to view accounts they contributed, including contributions to organizations they have not joined. **Reconnect** starts authorization again. **Disconnect** stops the organization from using that account in subsequent calls.

apps/docs/content/docs/workflows/blocks/credential.mdx

@@ -1,6 +1,6 @@
 ---
 title: Credential
-description: Select workspace OAuth credentials or find organization OAuth and MCP account references for downstream blocks.
+description: Select OAuth credentials, find Credential Group accounts, and use contributed API keys in downstream blocks.
 ---
 
 import { Callout } from 'fumadocs-ui/components/callout'
@@ -14,12 +14,12 @@ import {
 } from '@/components/workflow-preview'
 import { FAQ } from '@/components/ui/faq'
 
-The **Credential block** passes account references to downstream blocks without exposing tokens. **Select Credential** and **List Credentials** use workspace OAuth credentials. When [organization connected accounts](/platform/connected-accounts) is enabled and shared with the workflow's workspace, the organization operations find or list contributed OAuth accounts and managed MCP connections.
+The **Credential block** selects accounts and API keys for downstream blocks. **Select Credential** and **List Credentials** use workspace OAuth credentials. When [organization connected accounts](/platform/connected-accounts) is enabled and shared with the workflow's workspace, the Credential Group operations find or list contributed OAuth accounts, managed MCP connections, and named API keys.
 
 <BlockPreview type="credential" />
 
 <Callout>
-  The Credential block outputs credential **ID references**, not secrets. Downstream blocks receive the ID and resolve the actual OAuth token securely during their own execution.
+  OAuth and MCP operations return credential **ID references**. **List Credential Group API Keys** returns metadata and IDs. **Get Credential Group API Key** returns a usable `apiKey` value and registers it with secret provenance before releasing the output.
 </Callout>
 
 ## Configuration
@@ -30,10 +30,12 @@ The **Credential block** passes account references to downstream blocks without
 |---|---|
 | **Select Credential** | Pick one OAuth credential and output its reference — use this to wire a single credential into downstream blocks |
 | **List Credentials** | Return all OAuth credentials in the workspace as an array — use this with a ForEach loop |
-| **Find Organization Account** | Find exactly one active OAuth contribution by invitation email and provider |
-| **List Organization Accounts** | Return a page of active OAuth contributions, optionally filtered by email and providers |
-| **Find Organization MCP Connection** | Find exactly one active managed MCP connection by invitation email and MCP provider |
-| **List Organization MCP Connections** | Return a page of active managed MCP connections, optionally filtered by email and provider |
+| **Find Credential Group Account** | Find exactly one active OAuth contribution by invitation email and provider |
+| **List Credential Group Accounts** | Return a page of active OAuth contributions, optionally filtered by email and providers |
+| **Find Credential Group MCP Connection** | Find exactly one active managed MCP connection by invitation email and MCP provider |
+| **List Credential Group MCP Connections** | Return a page of active managed MCP connections, optionally filtered by email and provider |
+| **List Credential Group API Keys** | Return submitted key IDs and metadata, optionally filtered by key name and invitation email |
+| **Get Credential Group API Key** | Resolve the submitted key selected by an explicit credential ID |
 
 ### Credential (Select operation)
 
@@ -85,7 +87,7 @@ Every authorized workflow in an allowed workspace can discover active contributi
 
 ### Discover accounts by provider
 
-1. Choose **List Organization Accounts**.
+1. Choose **List Credential Group Accounts**.
 2. Select a provider such as **Gmail** in **Providers**. Leave it empty to list all allowed providers.
 3. Leave **Email** blank. You do not need to know an account's email to discover it.
 4. Read **emails** for the provider account addresses, or **credentials** for the corresponding account references.
@@ -97,10 +99,12 @@ Multiple accounts are returned separately, including accounts contributed by the
 
 | Operation | Required fields | Optional fields |
 | --- | --- | --- |
-| **Find Organization Account** | Email, Provider | — |
-| **List Organization Accounts** | — | Email, Providers, Limit, Cursor |
-| **Find Organization MCP Connection** | Email, MCP provider | — |
-| **List Organization MCP Connections** | — | Email, MCP provider, Limit, Cursor |
+| **Find Credential Group Account** | Email, Provider | — |
+| **List Credential Group Accounts** | — | Email, Providers, Limit, Cursor |
+| **Find Credential Group MCP Connection** | Email, MCP provider | — |
+| **List Credential Group MCP Connections** | — | Email, MCP provider, Limit, Cursor |
+| **List Credential Group API Keys** | — | Key name, Email, Limit, Cursor |
+| **Get Credential Group API Key** | API Key Credential ID | — |
 
 For list operations, **Limit** accepts 1–100 and defaults to 100. **Cursor** accepts the previous page's `nextCursor`.
 
@@ -110,17 +114,17 @@ Find operations fail unless there is exactly one active matching connection. Lis
 
 ### OAuth outputs
 
-**Find Organization Account** returns `credentialId`, `displayName`, `providerId`, and the invitation `email`. Pass `credentialId` into the corresponding integration block's credential field in advanced mode.
+**Find Credential Group Account** returns `credentialId`, `displayName`, `providerId`, and the invitation `email`. Pass `credentialId` into the corresponding integration block's credential field in advanced mode.
 
-**List Organization Accounts** returns these account references in `credentials`, with an additional `accountEmail` field containing the email verified by the OAuth provider. The existing `email` field remains the person's invitation address, which can differ from their provider account address. An optional **Email** input continues to filter by that exact invitation address.
+**List Credential Group Accounts** returns these account references in `credentials`, with an additional `accountEmail` field containing the email verified by the OAuth provider. The existing `email` field remains the person's invitation address, which can differ from their provider account address. An optional **Email** input continues to filter by that exact invitation address.
 
 The list also returns `emails`, `count`, `hasMore`, and `nextCursor`. `emails` contains the provider account addresses on this page in the same order as `credentials`; it preserves separate accounts even when addresses repeat. `count` is the number of accounts returned on this page. Feed `credentials` into a ForEach loop and use `<loop.currentItem.credentialId>` inside the loop. To process additional pages, pass `nextCursor` into another call with the same filters while `hasMore` is true; the block does not fetch all pages automatically.
 
-For example, name a Credential block **account**, choose **Find Organization Account**, set **Email** to `alex@example.com`, and select **Gmail**. Reference `<account.credentialId>` in a Gmail block to act using Alex's contribution.
+For example, name a Credential block **account**, choose **Find Credential Group Account**, set **Email** to `alex@example.com`, and select **Gmail**. Reference `<account.credentialId>` in a Gmail block to act using Alex's contribution.
 
 ### Managed MCP outputs
 
-**Find Organization MCP Connection** returns:
+**Find Credential Group MCP Connection** returns:
 
 | Output | Type | Description |
 | --- | --- | --- |
@@ -131,12 +135,27 @@ For example, name a Credential block **account**, choose **Find Organization Acc
 | `mcpServerName` | `string` | Configured MCP server name |
 | `toolNames` | `json` | Tool names available to this connection |
 
-**List Organization MCP Connections** returns these objects in `mcpConnections`, plus `count`, `hasMore`, and `nextCursor`. Pagination works the same way as for organization OAuth accounts; `nextCursor` is `null` on the last page.
+**List Credential Group MCP Connections** returns these objects in `mcpConnections`, plus `count`, `hasMore`, and `nextCursor`. Pagination works the same way as for organization OAuth accounts; `nextCursor` is `null` on the last page.
 
 <Callout>
 For a managed MCP account, use the returned **`credentialId`** to select the person's connection in the MCP Tool block. **`mcpServerId`** identifies the shared provider configuration; it does not identify a person's authorization. No OAuth token or client secret is returned by the Credential block.
 </Callout>
 
+### Named API keys
+
+An organization admin defines each key request with a name and an optional description. Each invited person supplies their own value. Names such as `Exa API key` and `EXA_API_KEY` are both accepted; the name is a label, not an environment variable. Renaming a request preserves its IDs and existing submissions.
+
+1. Use **List Credential Group API Keys**, optionally filtering by **Key name** and **Email**. Names match case-insensitively; an unknown name fails instead of listing unrelated keys.
+2. Select a returned `credentialId`, or iterate over `apiKeys` with a ForEach loop.
+3. In another Credential block named **GetKey**, choose **Get Credential Group API Key**. Set **API Key Credential ID** to the selected ID, such as `<loop.currentItem.credentialId>`.
+4. Use `<GetKey.apiKey>` in an integration's API-key field, or `Bearer <GetKey.apiKey>` in an HTTP Authorization header. No environment variable needs to be created.
+
+The list returns `apiKeys`, `count`, `hasMore`, and `nextCursor`. Each entry contains `credentialId`, `optionId`, `name`, and the invitation `email`; it contains no key value. Retrieval returns those fields plus `apiKey`. Workspace access, group status, and the contributor's current connection are checked again on retrieval. The executing user is used for authorization, not to select a key automatically.
+
+API key values are encrypted at rest and registered with secret provenance at retrieval. Retrieval fails if provenance cannot be registered. Values must be 8–4096 characters without surrounding whitespace. Removing a key request removes all submissions for that request; workflows using their IDs then fail.
+
+The previous **Find/List Organization Account** and **Find/List Organization MCP Connection** labels now say **Credential Group**. Their stored operation IDs and existing output fields are unchanged.
+
 ## Connection-event triggers
 
 Switch the Credential block to trigger mode to start a workflow when an account connects or a connection form is submitted. Select an **Event** and deploy the workflow in an allowed workspace.
@@ -147,7 +166,7 @@ Switch the Credential block to trigger mode to start a workflow when an account
 | **Credential Reconnected** | A person reconnects an existing contribution |
 | **Account Connections Submitted** | A person submits the connection form |
 
-Events include `event`, `timestamp`, `email`, `enrollmentId`, `enrollmentStatus`, `credentialGroupId`, and `credentialGroupName`. Added and reconnected events also include account details such as `credentialId`, `provider`, and `displayName`; `mcpServerId` identifies shared configuration for an MCP connection and is `null` for an OAuth account.
+Events include `event`, `timestamp`, `email`, `enrollmentId`, `enrollmentStatus`, `credentialGroupId`, and `credentialGroupName`. Adding or replacing an API key also emits the corresponding event with `provider: "api_key"` and metadata only. Added and reconnected events include account details such as `credentialId`, `provider`, and `displayName`; `mcpServerId` identifies shared configuration for an MCP connection and is `null` for an OAuth account.
 
 Each deployed workflow that selects the event in an allowed workspace can receive it. Removing workspace access stops subsequent event delivery. Legacy **Credential Group** blocks must be replaced with the Credential block; they are not automatically converted.
 

apps/sim/app/api/credential-groups/enroll/[token]/api-keys/[optionId]/route.test.ts

@@ -0,0 +1,117 @@
+/** @vitest-environment node */
+import { NextRequest, NextResponse } from 'next/server'
+import { beforeEach, expect, it, vi } from 'vitest'
+
+const mocks = vi.hoisted(() => ({
+  authenticate: vi.fn(),
+  save: vi.fn(),
+  remove: vi.fn(),
+  rateLimit: vi.fn(),
+}))
+vi.mock('@/lib/credential-groups/application/enrollment-auth', () => ({
+  authenticateCredentialGroupEnrollment: mocks.authenticate,
+}))
+vi.mock('@/lib/core/rate-limiter', () => ({
+  enforceUserRateLimit: mocks.rateLimit,
+  RateLimiter: class {},
+}))
+vi.mock('@/lib/credential-groups/application/public-enrollment', async () => {
+  const { credentialGroupEnrollmentOperations } = await import(
+    '@/lib/credential-groups/application/enrollment-operations'
+  )
+  return {
+    savePublicCredentialGroupApiKey: {
+      operation: credentialGroupEnrollmentOperations.saveApiKey,
+      execute: mocks.save,
+    },
+    deletePublicCredentialGroupApiKey: {
+      operation: credentialGroupEnrollmentOperations.deleteApiKey,
+      execute: mocks.remove,
+    },
+  }
+})
+
+import { CredentialGroupEnrollmentError } from '@/lib/credential-groups/enrollments'
+import { DELETE, PUT } from '@/app/api/credential-groups/enroll/[token]/api-keys/[optionId]/route'
+
+const optionId = '00000000-0000-4000-8000-000000000001'
+const params = { params: Promise.resolve({ token: 'invite-token', optionId }) }
+const principal = {
+  kind: 'credential_group_enrollment',
+  userId: 'person-1',
+  organizationId: 'org-1',
+  enrollmentId: 'enrollment-1',
+  credentialGroupId: 'group-1',
+  email: 'person@example.com',
+  invitationTokenHash: 'hash',
+}
+function request(body: string, method = 'PUT') {
+  return new NextRequest(
+    `http://localhost/api/credential-groups/enroll/invite-token/api-keys/${optionId}`,
+    {
+      method,
+      headers: { 'content-type': 'application/json' },
+      ...(method === 'PUT' ? { body } : {}),
+    }
+  )
+}
+beforeEach(() => {
+  vi.resetAllMocks()
+  mocks.authenticate.mockResolvedValue(principal)
+  mocks.save.mockResolvedValue({ connected: true })
+  mocks.remove.mockResolvedValue({ connected: false })
+  mocks.rateLimit.mockResolvedValue(null)
+})
+it('authenticates before parsing the submitted key', async () => {
+  mocks.authenticate.mockResolvedValue(null)
+  const response = await PUT(request('not-json'), params)
+  expect(response.status).toBe(401)
+  expect(mocks.save).not.toHaveBeenCalled()
+  expect(mocks.rateLimit).not.toHaveBeenCalled()
+})
+it('rate-limits the verified contributor before parsing', async () => {
+  mocks.rateLimit.mockResolvedValue(NextResponse.json({ error: 'Rate limited' }, { status: 429 }))
+  expect((await PUT(request('not-json'), params)).status).toBe(429)
+  expect(mocks.rateLimit).toHaveBeenCalledWith(
+    'credential-group-api-key',
+    'person-1',
+    expect.anything()
+  )
+  expect(mocks.save).not.toHaveBeenCalled()
+})
+it('returns only connection status and disables caching', async () => {
+  const response = await PUT(request(JSON.stringify({ value: 'fixture-secret' })), params)
+  expect(response.status).toBe(200)
+  expect(await response.json()).toEqual({ connected: true })
+  expect(response.headers.get('cache-control')).toBe('private, no-store')
+  expect(mocks.save).toHaveBeenCalledWith({
+    principal,
+    input: { optionId, value: 'fixture-secret' },
+    request: expect.any(NextRequest),
+  })
+})
+it.each([
+  { value: 'short' },
+  { value: 'fixture-secret', userId: 'other-person' },
+  { value: 'fixture-secret', unredacted: true },
+])('rejects invalid values and ownership overrides %j', async (body) => {
+  expect((await PUT(request(JSON.stringify(body)), params)).status).toBe(400)
+  expect(mocks.save).not.toHaveBeenCalled()
+})
+it('projects an invitation identity mismatch without exposing the submitted value', async () => {
+  mocks.save.mockRejectedValue(
+    new CredentialGroupEnrollmentError('Sign in with the invited email', 400)
+  )
+  const response = await PUT(request(JSON.stringify({ value: 'fixture-secret' })), params)
+  expect(response.status).toBe(400)
+  expect(await response.text()).not.toContain('fixture-secret')
+})
+it('disconnects only through the authenticated enrollment use case', async () => {
+  const response = await DELETE(request('', 'DELETE'), params)
+  expect(await response.json()).toEqual({ connected: false })
+  expect(mocks.remove).toHaveBeenCalledWith({
+    principal,
+    input: { optionId },
+    request: expect.any(NextRequest),
+  })
+})