---
title: Credentials
description: Manage secrets, API keys, and OAuth connections for your workflows
---

import { Callout } from 'fumadocs-ui/components/callout'
import { Image } from '@/components/ui/image'
import { Step, Steps } from 'fumadocs-ui/components/steps'
import { FAQ } from '@/components/ui/faq'

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.

Sim supports two categories of credentials: **secrets** for static values like API keys, and **OAuth accounts** for authenticated service connections like Google or Slack.

## Getting Started

To manage credentials, open your workspace **Settings** and navigate to the **Secrets** tab.

<Image
  src="/static/credentials/settings-secrets.png"
  alt="Settings modal showing the Secrets tab with a list of saved credentials"
  width={700}
  height={200}
/>

From here you can search, create, and delete both secrets and OAuth connections.

## Secrets

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).

### Creating a Secret

<Image
  src="/static/credentials/create-secret.png"
  alt="Create Secret dialog with fields for key, value, description, and scope toggle"
  width={500}
  height={400}
/>

<Steps>
  <Step>
    Click **+ Add** and select **Secret** as the type
  </Step>
  <Step>
    Enter a **Key** name (letters, numbers, and underscores only, e.g. `OPENAI_API_KEY`)
  </Step>
  <Step>
    Enter the **Value**
  </Step>
  <Step>
    Optionally add a **Description** to help your team understand what the secret is for
  </Step>
  <Step>
    Choose the **Scope** — Workspace or Personal
  </Step>
  <Step>
    Click **Create**
  </Step>
</Steps>

### Using Secrets in Workflows

To reference a secret in any input field, type `{{` to open the dropdown. It will show your available secrets grouped by scope.

<Image
  src="/static/credentials/secret-dropdown.png"
  alt="Typing {{ in a code block opens a dropdown showing available workspace secrets"
  width={400}
  height={250}
/>

Select the secret you want to use. The reference will appear highlighted in blue, indicating it will be resolved at runtime.

<Image
  src="/static/credentials/secret-resolved.png"
  alt="A resolved secret reference shown in blue text as {{OPENAI_API_KEY}}"
  width={400}
  height={200}
/>

<Callout type="warn">
Secret values are never exposed in the workflow editor or logs. They are only resolved during execution.
</Callout>

### Bulk Import

You can import multiple secrets at once by pasting `.env`-style content:

1. Click **+ Add**, then switch to **Bulk** mode
2. Paste your environment variables in `KEY=VALUE` format
3. Choose the scope for all imported secrets
4. Click **Create**

The parser supports standard `KEY=VALUE` pairs, quoted values, comments (`#`), and blank lines.

## OAuth Accounts

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.

You can connect **multiple accounts per provider** — for example, two separate Gmail accounts for different workflows.

### Connecting an OAuth Account

<Image
  src="/static/credentials/create-oauth.png"
  alt="Create Secret dialog with OAuth Account type selected, showing display name and provider dropdown"
  width={500}
  height={400}
/>

<Steps>
  <Step>
    Click **+ Add** and select **OAuth Account** as the type
  </Step>
  <Step>
    Enter a **Display name** to identify this connection (e.g. "Work Gmail" or "Marketing Slack")
  </Step>
  <Step>
    Optionally add a **Description**
  </Step>
  <Step>
    Select the **Account** provider from the dropdown
  </Step>
  <Step>
    Click **Connect** and complete the authorization flow
  </Step>
</Steps>

### Using OAuth Accounts in Workflows

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.

<Image
  src="/static/credentials/oauth-selector.png"
  alt="Gmail block showing the account selector dropdown with a connected account and option to connect another"
  width={500}
  height={350}
/>

You can also connect additional accounts directly from the block by selecting **Connect another account** at the bottom of the dropdown.

<Callout type="info">
If a block requires an OAuth connection and none is selected, the workflow will fail at that step.
</Callout>

## Workspace vs. Personal

Credentials can be scoped to your **workspace** (shared with your team) or kept **personal** (private to you).

| | Workspace | Personal |
|---|---|---|
| **Visibility** | All workspace members | Only you |
| **Use in workflows** | Any member can use | Only you can use |
| **Best for** | Production workflows, shared services | Testing, personal API keys |
| **Who can edit** | Workspace admins | Only you |
| **Auto-shared** | Yes — all members get access on creation | No — only you have access |

<Callout type="info">
When a workspace and personal secret share the same key name, the **workspace secret takes precedence**.
</Callout>

### Resolution Order

When a workflow runs, Sim resolves secrets in this order:

1. **Workspace secrets** are checked first
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)

## Access Control

Each credential has role-based access control:

- **Admin** — can view, edit, delete, and manage who has access
- **Member** — can use the credential in workflows (read-only)

When you create a workspace secret, all current workspace members are automatically granted access. Personal secrets are only accessible to you by default.

### Sharing a Credential

To share a credential with specific team members:

1. Click **Details** on the credential
2. Invite members by email
3. Assign them an **Admin** or **Member** role

## Best Practices

- **Use workspace credentials for production** so workflows work regardless of who triggers them
- **Use personal credentials for development** to keep your test keys separate
- **Name keys descriptively** — `STRIPE_SECRET_KEY` over `KEY1`
- **Connect multiple OAuth accounts** when you need different permissions or identities per workflow
- **Never hardcode secrets** in workflow input fields — always use `{{KEY}}` references

<FAQ items={[
  { question: "Are my secrets encrypted at rest?", answer: "Yes. Secret values and OAuth tokens are encrypted before being stored in the database. The platform uses server-side encryption so that raw secret values are never persisted in plaintext. Secret values are also never exposed in the workflow editor, logs, or API responses." },
  { question: "What happens if both a workspace secret and a personal secret have the same key name?", answer: "The workspace secret takes precedence. During execution, the resolver checks workspace secrets first and uses personal secrets only as a fallback. This ensures that production workflows use the shared, team-managed value." },
  { question: "Who determines which personal secret is used for automated runs?", answer: "For manual runs, the personal secrets of the user who clicked Run are used as fallback. For automated runs triggered by API, webhook, or schedule, the personal secrets of the workflow owner are used instead." },
  { question: "Does Sim handle OAuth token refresh automatically?", answer: "Yes. When an OAuth token is used during execution, the platform checks whether the access token has expired and automatically refreshes it using the stored refresh token before making the API call. You do not need to handle token refresh manually." },
  { question: "Can I connect multiple OAuth accounts for the same provider?", answer: "Yes. You can connect multiple accounts per provider (for example, two separate Gmail accounts). Each block that requires OAuth lets you select which specific account to use from the credential dropdown. This is useful when different workflows or blocks need different permissions or identities." },
  { question: "What happens if I delete a credential that is used in a workflow?", answer: "If a block references a deleted credential, the workflow will fail at that block during execution because the credential cannot be resolved. Make sure to update any blocks that reference a credential before deleting it." },
  { question: "Can I import secrets from a .env file?", answer: "Yes. The bulk import feature lets you paste .env-style content in KEY=VALUE format. The parser supports quoted values, comments (lines starting with #), and blank lines. All imported secrets are created with the scope you choose (workspace or personal)." },
]} />
