|
| 1 | +--- |
| 2 | +title: Credential |
| 3 | +--- |
| 4 | + |
| 5 | +import { Callout } from 'fumadocs-ui/components/callout' |
| 6 | +import { Tab, Tabs } from 'fumadocs-ui/components/tabs' |
| 7 | +import { Image } from '@/components/ui/image' |
| 8 | +import { FAQ } from '@/components/ui/faq' |
| 9 | + |
| 10 | +The Credential block has two operations: **Select Credential** picks a single OAuth credential and outputs its ID reference for downstream blocks; **List Credentials** returns all OAuth credentials in the workspace (optionally filtered by provider) as an array for iteration. |
| 11 | + |
| 12 | +<div className="flex justify-center"> |
| 13 | + <Image |
| 14 | + src="/static/blocks/credential.png" |
| 15 | + alt="Credential Block" |
| 16 | + width={400} |
| 17 | + height={300} |
| 18 | + className="my-6" |
| 19 | + /> |
| 20 | +</div> |
| 21 | + |
| 22 | +<Callout> |
| 23 | + 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. |
| 24 | +</Callout> |
| 25 | + |
| 26 | +## Configuration Options |
| 27 | + |
| 28 | +### Operation |
| 29 | + |
| 30 | +| Value | Description | |
| 31 | +|---|---| |
| 32 | +| **Select Credential** | Pick one OAuth credential and output its reference — use this to wire a single credential into downstream blocks | |
| 33 | +| **List Credentials** | Return all OAuth credentials in the workspace as an array — use this with a ForEach loop | |
| 34 | + |
| 35 | +### Credential (Select operation) |
| 36 | + |
| 37 | +Select an OAuth credential from your workspace. The dropdown shows all connected OAuth accounts (Google, GitHub, Slack, etc.). |
| 38 | + |
| 39 | +In advanced mode, paste a credential ID directly. You can copy a credential ID from your workspace's Credentials settings page. |
| 40 | + |
| 41 | +### Provider (List operation) |
| 42 | + |
| 43 | +Filter the returned 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 credentials. |
| 44 | + |
| 45 | +| Example | Returns | |
| 46 | +|---|---| |
| 47 | +| Gmail | Gmail credentials only | |
| 48 | +| Slack | Slack credentials only | |
| 49 | +| Gmail + Slack | Gmail and Slack credentials | |
| 50 | + |
| 51 | +## Outputs |
| 52 | + |
| 53 | +<Tabs items={['Select Credential', 'List Credentials']}> |
| 54 | + <Tab> |
| 55 | + | Output | Type | Description | |
| 56 | + |---|---|---| |
| 57 | + | `credentialId` | `string` | The credential ID — pipe this into other blocks' credential fields | |
| 58 | + | `displayName` | `string` | Human-readable name (e.g. "waleed@company.com") | |
| 59 | + | `providerId` | `string` | OAuth provider ID (e.g. `google-email`, `slack`) | |
| 60 | + </Tab> |
| 61 | + <Tab> |
| 62 | + | Output | Type | Description | |
| 63 | + |---|---|---| |
| 64 | + | `credentials` | `json` | Array of OAuth credential objects (see shape below) | |
| 65 | + | `count` | `number` | Number of credentials returned | |
| 66 | + |
| 67 | + Each object in the `credentials` array: |
| 68 | + |
| 69 | + | Field | Type | Description | |
| 70 | + |---|---|---| |
| 71 | + | `credentialId` | `string` | The credential ID | |
| 72 | + | `displayName` | `string` | Human-readable name | |
| 73 | + | `providerId` | `string` | OAuth provider ID | |
| 74 | + </Tab> |
| 75 | +</Tabs> |
| 76 | + |
| 77 | +## Example Use Cases |
| 78 | + |
| 79 | +**Shared credential across multiple blocks** — Define once, use everywhere |
| 80 | +``` |
| 81 | +Credential (Select, Google) → Gmail (Send) & Google Drive (Upload) & Google Calendar (Create) |
| 82 | +``` |
| 83 | + |
| 84 | +**Multi-account workflows** — Route to different credentials based on logic |
| 85 | +``` |
| 86 | +Agent (Determine account) → Condition → Credential A or Credential B → Slack (Post) |
| 87 | +``` |
| 88 | + |
| 89 | +**Iterate over all Gmail accounts** |
| 90 | +``` |
| 91 | +Credential (List, Provider: Gmail) → ForEach Loop → Gmail (Send) using <loop.currentItem.credentialId> |
| 92 | +``` |
| 93 | + |
| 94 | +<div className="flex justify-center"> |
| 95 | + <Image |
| 96 | + src="/static/blocks/credential-loop.png" |
| 97 | + alt="Credential List wired into a ForEach Loop" |
| 98 | + width={900} |
| 99 | + height={400} |
| 100 | + className="my-6" |
| 101 | + /> |
| 102 | +</div> |
| 103 | + |
| 104 | +## How to wire a Credential block |
| 105 | + |
| 106 | +### Select Credential |
| 107 | + |
| 108 | +1. Drop a **Credential** block and select your OAuth credential from the picker |
| 109 | +2. In the downstream block, switch to **advanced mode** on its credential field |
| 110 | +3. Enter `<credentialBlockName.credentialId>` as the value |
| 111 | + |
| 112 | +<Tabs items={['Gmail', 'Slack']}> |
| 113 | + <Tab> |
| 114 | + In the Gmail block's credential field (advanced mode): |
| 115 | + ``` |
| 116 | + <myCredential.credentialId> |
| 117 | + ``` |
| 118 | + </Tab> |
| 119 | + <Tab> |
| 120 | + In the Slack block's credential field (advanced mode): |
| 121 | + ``` |
| 122 | + <myCredential.credentialId> |
| 123 | + ``` |
| 124 | + </Tab> |
| 125 | +</Tabs> |
| 126 | + |
| 127 | +### List Credentials |
| 128 | + |
| 129 | +1. Drop a **Credential** block, set Operation to **List Credentials** |
| 130 | +2. Optionally select one or more **Providers** to narrow results (only your connected providers appear) |
| 131 | +3. Wire `<credentialBlockName.credentials>` into a **ForEach Loop** as the items source |
| 132 | +4. Inside the loop, reference `<loop.currentItem.credentialId>` in downstream blocks' credential fields |
| 133 | + |
| 134 | +## Best Practices |
| 135 | + |
| 136 | +- **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 |
| 137 | +- **Outputs are safe to log**: The `credentialId` output is a UUID reference, not a secret. It is safe to inspect in execution logs |
| 138 | +- **Use for environment switching**: Pair with a Condition block to route to a production or staging OAuth credential based on a workflow variable |
| 139 | +- **Advanced mode is required**: Downstream blocks must be in advanced mode on their credential field to accept a dynamic reference |
| 140 | +- **Use List + ForEach for fan-out**: When you need to run the same action across all accounts of a provider, List Credentials feeds naturally into a ForEach loop |
| 141 | +- **Narrow by provider**: Use the Provider multiselect to filter to specific services — only providers you have credentials for are shown |
| 142 | + |
| 143 | +<FAQ items={[ |
| 144 | + { question: "Does the Credential block expose my secret or token?", answer: "No. The block outputs a credential ID (a UUID), not the actual OAuth token. Downstream blocks receive the ID and resolve the token securely in their own execution context. Secrets never appear in workflow state, logs, or the canvas." }, |
| 145 | + { question: "What credential types does it support?", answer: "OAuth connected accounts only (Google, GitHub, Slack, etc.). Environment variables and service accounts cannot be resolved by ID in downstream blocks, so they are not supported." }, |
| 146 | + { 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." }, |
| 147 | + { question: "Can I list all OAuth credentials in my workspace?", answer: "Yes. Set the Operation to 'List Credentials'. Optionally filter by provider using the Provider multiselect. Wire the credentials output into a ForEach loop to process each credential individually." }, |
| 148 | + { 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." }, |
| 149 | + { 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." }, |
| 150 | +]} /> |
0 commit comments