feat(credential): add list operation with type/provider filters

Author: waleedlatif1

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

@@ -7,25 +7,32 @@ import { Tab, Tabs } from 'fumadocs-ui/components/tabs'
 import { Image } from '@/components/ui/image'
 import { FAQ } from '@/components/ui/faq'
 
-The Credential block selects a stored credential once and passes its ID to any downstream block that requires authentication. The credential is resolved securely at execution time — no secrets are exposed in the workflow state or logs.
+The Credential block has two operations: **Select Credential** picks a single stored credential and outputs its ID reference for downstream blocks; **List Credentials** returns all credentials in the workspace (optionally filtered by type) as an array for iteration.
 
 <div className="flex justify-center">
   <Image
     src="/static/blocks/credential.png"
     alt="Credential Block"
-    width={500}
-    height={400}
+    width={400}
+    height={300}
     className="my-6"
   />
 </div>
 
 <Callout>
-  The Credential block outputs a credential **ID reference**, not the secret itself. Downstream blocks receive the ID and resolve it securely during their own execution.
+  The Credential block outputs credential **ID references**, not secrets. Downstream blocks receive the ID and resolve it securely during their own execution.
 </Callout>
 
 ## Configuration Options
 
-### Credential
+### Operation
+
+| Value | Description |
+|---|---|
+| **Select Credential** | Pick one credential and output its reference — use this to wire a single credential into downstream blocks |
+| **List Credentials** | Return all workspace credentials as an array — use this with a ForEach loop |
+
+### Credential (Select operation)
 
 Select a credential from your workspace. The dropdown shows all credential types you have access to, grouped by category:
 
@@ -35,20 +42,61 @@ Select a credential from your workspace. The dropdown shows all credential types
 
 In advanced mode, paste a credential ID directly. You can copy a credential ID from your workspace's Credentials settings page.
 
+### Type Filter (List operation)
+
+Filter the returned credentials by type. Defaults to **All**.
+
+| Value | Description |
+|---|---|
+| **All** | Return all credential types |
+| **OAuth** | Connected OAuth accounts only |
+| **Env Variables (Workspace)** | Workspace environment variables only |
+| **Env Variables (Personal)** | Personal environment variables only |
+| **Service Accounts** | Google service account keys only |
+
+### Provider (List operation, OAuth only)
+
+Further filter OAuth credentials by provider. Select one or more providers from the dropdown — only providers you have credentials for will appear. Leave empty to return all OAuth providers.
+
+| Example | Returns |
+|---|---|
+| Gmail | Gmail credentials only |
+| Slack | Slack credentials only |
+| Gmail + Slack | Gmail and Slack credentials |
+
 ## Outputs
 
-| Output | Type | Description |
-|---|---|---|
-| `credentialId` | `string` | The credential ID — pipe this into other blocks' credential fields |
-| `displayName` | `string` | Human-readable name (e.g. "waleed@company.com") |
-| `type` | `string` | `oauth` \| `env_workspace` \| `env_personal` \| `service_account` |
-| `providerId` | `string` | OAuth provider (e.g. `google`, `github`), empty for non-OAuth types |
+<Tabs items={['Select Credential', 'List Credentials']}>
+  <Tab>
+    | Output | Type | Description |
+    |---|---|---|
+    | `credentialId` | `string` | The credential ID — pipe this into other blocks' credential fields |
+    | `displayName` | `string` | Human-readable name (e.g. "waleed@company.com") |
+    | `type` | `string` | `oauth` \| `env_workspace` \| `env_personal` \| `service_account` |
+    | `providerId` | `string` | OAuth provider (e.g. `google`, `github`), empty for non-OAuth types |
+  </Tab>
+  <Tab>
+    | Output | Type | Description |
+    |---|---|---|
+    | `credentials` | `json` | Array of credential objects (see shape below) |
+    | `count` | `number` | Number of credentials returned |
+
+    Each object in the `credentials` array:
+
+    | Field | Type | Description |
+    |---|---|---|
+    | `credentialId` | `string` | The credential ID |
+    | `displayName` | `string` | Human-readable name |
+    | `type` | `string` | Credential type |
+    | `providerId` | `string` | OAuth provider ID, empty for non-OAuth |
+  </Tab>
+</Tabs>
 
 ## Example Use Cases
 
 **Shared credential across multiple blocks** — Define once, use everywhere
 ```
-Credential (Google) → Gmail (Send) & Google Drive (Upload) & Google Calendar (Create)
+Credential (Select, Google) → Gmail (Send) & Google Drive (Upload) & Google Calendar (Create)
 ```
 
 **Environment switching** — Swap credentials without touching downstream blocks
@@ -62,8 +110,25 @@ Condition (env === 'prod') → Credential (Prod API Key) or Credential (Dev API
 Agent (Determine account) → Condition → Credential A or Credential B → Slack (Post)
 ```
 
+**Iterate over all Gmail accounts**
+```
+Credential (List, OAuth, Provider: Gmail) → ForEach Loop → Gmail (Send) using <loop.currentItem.credentialId>
+```
+
+<div className="flex justify-center">
+  <Image
+    src="/static/blocks/credential-loop.png"
+    alt="Credential List wired into a ForEach Loop"
+    width={900}
+    height={400}
+    className="my-6"
+  />
+</div>
+
 ## How to wire a Credential block
 
+### Select Credential
+
 1. Drop a **Credential** block and select your credential from the picker
 2. In the downstream block, switch to **advanced mode** on its credential field
 3. Enter `<credentialBlockName.credentialId>` as the value
@@ -90,17 +155,28 @@ Agent (Determine account) → Condition → Credential A or Credential B → Sla
   </Tab>
 </Tabs>
 
+### List Credentials
+
+1. Drop a **Credential** block, set Operation to **List Credentials**
+2. Optionally set a **Type Filter** (e.g. OAuth only)
+3. Optionally select one or more **Providers** to narrow results (only your connected providers appear)
+4. Wire `<credentialBlockName.credentials>` into a **ForEach Loop** as the items source
+5. Inside the loop, reference `<loop.currentItem.credentialId>` in downstream blocks' credential fields
+
 ## Best Practices
 
 - **Define once, reference many times**: When five blocks use the same Google account, use one Credential block and wire all five to `<credential.credentialId>` instead of selecting the account five times
 - **Outputs are safe to log**: The `credentialId` output is a UUID reference, not a secret. It is safe to inspect in execution logs
 - **Use for environment switching**: Pair with a Condition block to route to a production or staging credential based on a workflow variable
 - **Advanced mode is required**: Downstream blocks must be in advanced mode on their credential field to accept a dynamic reference
+- **Use List + ForEach for fan-out**: When you need to run the same action across all accounts of a type, List Credentials feeds naturally into a ForEach loop
+- **Narrow by provider**: Use the Provider multiselect to filter to specific services — only providers you have credentials for are shown
 
 <FAQ items={[
   { question: "Does the Credential block expose my secret or token?", answer: "No. The block outputs a credential ID (a UUID), not the actual secret or token. Downstream blocks receive the ID and resolve it securely in their own execution context. Secrets never appear in workflow state, logs, or the canvas." },
   { question: "What credential types does it support?", answer: "All credential types: OAuth connected accounts, workspace environment variables, personal environment variables, and Google service accounts." },
-  { question: "How is this different from just copying a credential ID into advanced mode?", answer: "Functionally identical — both pass the same credential ID to the downstream block. The Credential block adds value when you need to use one credential in many blocks (change it once), or when you want to select between credentials dynamically using a Condition block." },
+  { question: "How is Select different from just copying a credential ID into advanced mode?", answer: "Functionally identical — both pass the same credential ID to the downstream block. The Credential block adds value when you need to use one credential in many blocks (change it once), or when you want to select between credentials dynamically using a Condition block." },
+  { question: "Can I list all credentials in my workspace?", answer: "Yes. Set the Operation to 'List Credentials'. You can optionally filter by type (OAuth, environment variables, service accounts). Wire the credentials output into a ForEach loop to process each credential individually." },
   { question: "Can I use a Credential block output in a Function block?", answer: "Yes. Reference <credential.credentialId> in your Function block's code. Note that the function will receive the raw UUID string — if you need the resolved token, the downstream block must handle the resolution (as integration blocks do). The Function block does not automatically resolve credential IDs." },
-  { question: "What happens if the credential is deleted?", answer: "The block will throw an error at execution time: 'Credential not found or access denied'. Update the Credential block to select a valid credential before re-running." },
+  { question: "What happens if the credential is deleted?", answer: "The Select operation will throw an error at execution time: 'Credential not found'. The List operation will simply omit the deleted credential from the results. Update the Credential block to select a valid credential before re-running." },
 ]} />

apps/docs/public/static/blocks/credential-loop.png

@@ -59,14 +59,10 @@ interface ComboBoxProps {
   /** Configuration for the sub-block */
   config: SubBlockConfig
   /** Async function to fetch options dynamically */
-  fetchOptions?: (
-    blockId: string,
-    subBlockId: string
-  ) => Promise<Array<{ label: string; id: string }>>
+  fetchOptions?: (blockId: string) => Promise<Array<{ label: string; id: string }>>
   /** Async function to fetch a single option's label by ID (for hydration) */
   fetchOptionById?: (
     blockId: string,
-    subBlockId: string,
     optionId: string
   ) => Promise<{ label: string; id: string } | null>
   /** Field dependencies that trigger option refetch when changed */
@@ -135,7 +131,7 @@ export const ComboBox = memo(function ComboBox({
     setIsLoadingOptions(true)
     setFetchError(null)
     try {
-      const options = await fetchOptions(blockId, subBlockId)
+      const options = await fetchOptions(blockId)
       setFetchedOptions(options)
     } catch (error) {
       const errorMessage = error instanceof Error ? error.message : 'Failed to fetch options'
@@ -144,7 +140,7 @@ export const ComboBox = memo(function ComboBox({
     } finally {
       setIsLoadingOptions(false)
     }
-  }, [fetchOptions, blockId, subBlockId, isPreview, disabled])
+  }, [fetchOptions, blockId, isPreview, disabled])
 
   // Determine the active value based on mode (preview vs. controlled vs. store)
   const value = isPreview ? previewValue : propValue !== undefined ? propValue : storeValue
@@ -363,7 +359,7 @@ export const ComboBox = memo(function ComboBox({
     let isActive = true
 
     // Fetch the hydrated option
-    fetchOptionById(blockId, subBlockId, valueToHydrate)
+    fetchOptionById(blockId, valueToHydrate)
       .then((option) => {
         if (isActive) setHydratedOption(option)
       })
@@ -378,7 +374,6 @@ export const ComboBox = memo(function ComboBox({
     fetchOptionById,
     value,
     blockId,
-    subBlockId,
     isPreview,
     disabled,
     fetchedOptions,

apps/docs/public/static/blocks/credential.png

@@ -52,14 +52,10 @@ interface DropdownProps {
   /** Enable multi-select mode */
   multiSelect?: boolean
   /** Async function to fetch options dynamically */
-  fetchOptions?: (
-    blockId: string,
-    subBlockId: string
-  ) => Promise<Array<{ label: string; id: string }>>
+  fetchOptions?: (blockId: string) => Promise<Array<{ label: string; id: string }>>
   /** Async function to fetch a single option's label by ID (for hydration) */
   fetchOptionById?: (
     blockId: string,
-    subBlockId: string,
     optionId: string
   ) => Promise<{ label: string; id: string } | null>
   /** Field dependencies that trigger option refetch when changed */
@@ -160,7 +156,7 @@ export const Dropdown = memo(function Dropdown({
     setIsLoadingOptions(true)
     setFetchError(null)
     try {
-      const options = await fetchOptions(blockId, subBlockId)
+      const options = await fetchOptions(blockId)
       setFetchedOptions(options)
     } catch (error) {
       const errorMessage = error instanceof Error ? error.message : 'Failed to fetch options'
@@ -169,7 +165,7 @@ export const Dropdown = memo(function Dropdown({
     } finally {
       setIsLoadingOptions(false)
     }
-  }, [fetchOptions, blockId, subBlockId, isPreview, disabled])
+  }, [fetchOptions, blockId, isPreview, disabled])
 
   /**
    * Handles combobox open state changes to trigger option fetching
@@ -430,7 +426,7 @@ export const Dropdown = memo(function Dropdown({
     let isActive = true
 
     // Fetch the hydrated option
-    fetchOptionById(blockId, subBlockId, valueToHydrate)
+    fetchOptionById(blockId, valueToHydrate)
       .then((option) => {
         if (isActive) setHydratedOption(option)
       })
@@ -446,7 +442,6 @@ export const Dropdown = memo(function Dropdown({
     singleValue,
     multiSelect,
     blockId,
-    subBlockId,
     isPreview,
     disabled,
     fetchedOptions,