Skip to content

Commit ff01825

Browse files
waleedlatif1waleedlatif1
authored
docs(credentials): replace environment variables page with credentials docs (#3331)
1 parent 58d0fda commit ff01825

File tree

14 files changed

+193
-576
lines changed

14 files changed

+193
-576
lines changed

‎apps/docs/content/docs/de/variables/environment-variables.mdx‎

Lines changed: 0 additions & 96 deletions
This file was deleted.

‎apps/docs/content/docs/en/credentials/index.mdx‎

Lines changed: 192 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,192 @@
1+
---
2+
title: Credentials
3+
description: Manage secrets, API keys, and OAuth connections for your workflows
4+
---
5+
6+
import { Callout } from 'fumadocs-ui/components/callout'
7+
import { Image } from '@/components/ui/image'
8+
import { Step, Steps } from 'fumadocs-ui/components/steps'
9+
10+
Credentials provide a secure way to manage API keys, tokens, and third-party service connections across your workflows. Instead of hardcoding sensitive values into your workflow, you store them as credentials and reference them at runtime.
11+
12+
Sim supports two categories of credentials: **secrets** for static values like API keys, and **OAuth accounts** for authenticated service connections like Google or Slack.
13+
14+
## Getting Started
15+
16+
To manage credentials, open your workspace **Settings** and navigate to the **Secrets** tab.
17+
18+
<Image
19+
src="/static/credentials/settings-secrets.png"
20+
alt="Settings modal showing the Secrets tab with a list of saved credentials"
21+
width={700}
22+
height={200}
23+
/>
24+
25+
From here you can search, create, and delete both secrets and OAuth connections.
26+
27+
## Secrets
28+
29+
Secrets are key-value pairs that store sensitive data like API keys, tokens, and passwords. Each secret has a **key** (used to reference it in workflows) and a **value** (the actual secret).
30+
31+
### Creating a Secret
32+
33+
<Image
34+
src="/static/credentials/create-secret.png"
35+
alt="Create Secret dialog with fields for key, value, description, and scope toggle"
36+
width={500}
37+
height={400}
38+
/>
39+
40+
<Steps>
41+
<Step>
42+
Click **+ Add** and select **Secret** as the type
43+
</Step>
44+
<Step>
45+
Enter a **Key** name (letters, numbers, and underscores only, e.g. `OPENAI_API_KEY`)
46+
</Step>
47+
<Step>
48+
Enter the **Value**
49+
</Step>
50+
<Step>
51+
Optionally add a **Description** to help your team understand what the secret is for
52+
</Step>
53+
<Step>
54+
Choose the **Scope** — Workspace or Personal
55+
</Step>
56+
<Step>
57+
Click **Create**
58+
</Step>
59+
</Steps>
60+
61+
### Using Secrets in Workflows
62+
63+
To reference a secret in any input field, type `{{` to open the dropdown. It will show your available secrets grouped by scope.
64+
65+
<Image
66+
src="/static/credentials/secret-dropdown.png"
67+
alt="Typing {{ in a code block opens a dropdown showing available workspace secrets"
68+
width={400}
69+
height={250}
70+
/>
71+
72+
Select the secret you want to use. The reference will appear highlighted in blue, indicating it will be resolved at runtime.
73+
74+
<Image
75+
src="/static/credentials/secret-resolved.png"
76+
alt="A resolved secret reference shown in blue text as {{OPENAI_API_KEY}}"
77+
width={400}
78+
height={200}
79+
/>
80+
81+
<Callout type="warn">
82+
Secret values are never exposed in the workflow editor or logs. They are only resolved during execution.
83+
</Callout>
84+
85+
### Bulk Import
86+
87+
You can import multiple secrets at once by pasting `.env`-style content:
88+
89+
1. Click **+ Add**, then switch to **Bulk** mode
90+
2. Paste your environment variables in `KEY=VALUE` format
91+
3. Choose the scope for all imported secrets
92+
4. Click **Create**
93+
94+
The parser supports standard `KEY=VALUE` pairs, quoted values, comments (`#`), and blank lines.
95+
96+
## OAuth Accounts
97+
98+
OAuth accounts are authenticated connections to third-party services like Google, Slack, GitHub, and more. Sim handles the OAuth flow, token storage, and automatic refresh.
99+
100+
You can connect **multiple accounts per provider** — for example, two separate Gmail accounts for different workflows.
101+
102+
### Connecting an OAuth Account
103+
104+
<Image
105+
src="/static/credentials/create-oauth.png"
106+
alt="Create Secret dialog with OAuth Account type selected, showing display name and provider dropdown"
107+
width={500}
108+
height={400}
109+
/>
110+
111+
<Steps>
112+
<Step>
113+
Click **+ Add** and select **OAuth Account** as the type
114+
</Step>
115+
<Step>
116+
Enter a **Display name** to identify this connection (e.g. "Work Gmail" or "Marketing Slack")
117+
</Step>
118+
<Step>
119+
Optionally add a **Description**
120+
</Step>
121+
<Step>
122+
Select the **Account** provider from the dropdown
123+
</Step>
124+
<Step>
125+
Click **Connect** and complete the authorization flow
126+
</Step>
127+
</Steps>
128+
129+
### Using OAuth Accounts in Workflows
130+
131+
Blocks that require authentication (e.g. Gmail, Slack, Google Sheets) display a credential selector dropdown. Select the OAuth account you want the block to use.
132+
133+
<Image
134+
src="/static/credentials/oauth-selector.png"
135+
alt="Gmail block showing the account selector dropdown with a connected account and option to connect another"
136+
width={500}
137+
height={350}
138+
/>
139+
140+
You can also connect additional accounts directly from the block by selecting **Connect another account** at the bottom of the dropdown.
141+
142+
<Callout type="info">
143+
If a block requires an OAuth connection and none is selected, the workflow will fail at that step.
144+
</Callout>
145+
146+
## Workspace vs. Personal
147+
148+
Credentials can be scoped to your **workspace** (shared with your team) or kept **personal** (private to you).
149+
150+
| | Workspace | Personal |
151+
|---|---|---|
152+
| **Visibility** | All workspace members | Only you |
153+
| **Use in workflows** | Any member can use | Only you can use |
154+
| **Best for** | Production workflows, shared services | Testing, personal API keys |
155+
| **Who can edit** | Workspace admins | Only you |
156+
| **Auto-shared** | Yes — all members get access on creation | No — only you have access |
157+
158+
<Callout type="info">
159+
When a workspace and personal secret share the same key name, the **workspace secret takes precedence**.
160+
</Callout>
161+
162+
### Resolution Order
163+
164+
When a workflow runs, Sim resolves secrets in this order:
165+
166+
1. **Workspace secrets** are checked first
167+
2. **Personal secrets** are used as a fallback — from the user who triggered the run (manual) or the workflow owner (automated runs via API, webhook, or schedule)
168+
169+
## Access Control
170+
171+
Each credential has role-based access control:
172+
173+
- **Admin** — can view, edit, delete, and manage who has access
174+
- **Member** — can use the credential in workflows (read-only)
175+
176+
When you create a workspace secret, all current workspace members are automatically granted access. Personal secrets are only accessible to you by default.
177+
178+
### Sharing a Credential
179+
180+
To share a credential with specific team members:
181+
182+
1. Click **Details** on the credential
183+
2. Invite members by email
184+
3. Assign them an **Admin** or **Member** role
185+
186+
## Best Practices
187+
188+
- **Use workspace credentials for production** so workflows work regardless of who triggers them
189+
- **Use personal credentials for development** to keep your test keys separate
190+
- **Name keys descriptively** — `STRIPE_SECRET_KEY` over `KEY1`
191+
- **Connect multiple OAuth accounts** when you need different permissions or identities per workflow
192+
- **Never hardcode secrets** in workflow input fields — always use `{{KEY}}` references

‎apps/docs/content/docs/en/meta.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,7 @@
1313
"skills",
1414
"knowledgebase",
1515
"variables",
16+
"credentials",
1617
"execution",
1718
"permissions",
1819
"sdks",

‎apps/docs/content/docs/en/variables/environment-variables.mdx‎

Lines changed: 0 additions & 96 deletions
This file was deleted.

0 commit comments

Comments
 (0)