Automation Credentials (saved secrets for v2 actions)

What it is

The Automation Credentials manager is where you store the API tokens, webhook URLs, service-account keys, and SMTP passwords that the new v2 automation actions need at run time. Without it, every Slack / GitHub / SMTP action would have to embed its secret in the action's JSON config — which would leak it into the database row, into automation backups, and into the inbox approval payload an external AI sees before you click Approve. Instead, an action carries only a credentialId reference, and the executor resolves the real secret from this manager (decrypted in the main process) at the moment it needs it.

Where to find it

How to use it

1. Open the panel. Go to Settings → Automations → Credentials (the Credentials tab of the Automations hub, key icon). The header explains what credentials are and confirms that secrets are encrypted using the OS keyring.

2. Decide whether you need the high-risk gate. The first control is a toggle labeled Allow high-risk credential kinds. It's off by default. Two of the nine credential kinds are classified high-risk because they hand out broad data access or outbound-abuse potential: google-service-account (broad GCP / Workspace access on the project the key belongs to) and smtp (full outbound mail relay, useful as a spam / phishing vector if leaked). With the toggle off, you can still view, rename, and delete an existing high-risk credential, but creating a new one or rotating its secret is blocked at the IPC handler with a clear error message. The other seven kinds (Slack, GitHub, Sentry, Discord webhook, Notion, Telegram, generic HTTP auth) are scoped enough to never be gated.

3. Add a credential. Click Add credential at the bottom of the list. A modal titled New credential opens with three fields: a Kind dropdown populated from the registry (slack, github, sentry, discord-webhook, notion-token, telegram-bot, http-auth, google-service-account, smtp), a friendly Name so you can find it later, and a per-kind secret editor that swaps fields based on the kind you pick:

   • slack / telegram-bot — single Bot token password field
   • github / sentry / notion-token — single Token password field
   • discord-webhook — Webhook URL text field
   • http-auth — Scheme selector (bearer / basic / header) with the matching sub-fields underneath
   • google-service-account — Client email plus a tall monospaced Private key textarea
   • smtp — Host, Port, TLS checkbox, Username, Password

   Press Save (or Ctrl+Enter / Cmd+Enter anywhere inside the modal). The server validates the secret shape against the per-kind Zod schema before encrypting; a mismatch surfaces inline as a red error message in the modal — no save happens.

4. Use it in an action. Open an automation in the v2 editor. For any action that has a credentialKind field (currently slack.send-message, discord.send-message, email.send-via-smtp, github.add-comment, github.create-issue, google-sheets.append-row, http.request, notion.append-block, notion.create-page, and telegram.send-message), the config panel renders a compact <select> — the Credential picker — with the placeholder — Pick a saved credential — and one option per credential of that kind. If the high-risk gate is off, gated rows render disabled with a trailing (blocked) suffix and a callout below the picker links you back to the toggle. If you have no credentials of that kind yet, the picker shows an empty-state with an Add credential button that deep-links to this Settings page.

5. Rotate or rename a credential. Each list row has three buttons: Rename, Rotate, Delete. Rename opens an inline name-only editor — never gated. Rotate opens an inline secret-only editor with the same per-kind fields as the create modal; rotating a high-risk credential re-checks the gate. Delete prompts you with a danger-variant confirmation explaining that any automations using the credential will fail until you pick a replacement.

6. The id is what gets referenced. Actions point at credentials by their UUID, not by name — so renaming a credential is safe (no automations break) but deleting one is destructive. When the credential is missing at run time, the resolver throws a clear, user-actionable error into the automation run log instead of silently no-op'ing with an empty secret.

How it behaves

How it works

The settings panel lives at ../../src/renderer/src/features/settings/sections/automation-credentials/AutomationCredentialsSettings.tsx and is the sole consumer of useAutomationCredentialsStore() from ../../src/renderer/src/stores/automation-credentials-store.ts. The store is a thin Zustand wrapper over four IPC handlers — automation:credential-list / -create / -update / -delete — defined in ../../src/main/ipc/automation-credential-handlers.ts. The store deliberately re-fetches after every mutation rather than merging optimistically: the encrypted-blob round-trip means a parallel un-encrypted shadow copy would be the only way to merge locally, and the operations are infrequent enough that a refetch is cheap.

The nine per-kind Zod schemas + the high-risk allow-list live in ../../src/shared/automation-credential-schemas.ts so both processes import the same source of truth. The credential service at ../../src/main/services/automation/legacy/automation-credentials.ts layers four guarantees on top of the dumb persistence layer:

• Encryption — delegated to the canonical encryptCredential / decryptCredential helpers, which prefix the ciphertext with enc: and use Electron's safeStorage (Windows DPAPI / macOS Keychain / Linux libsecret). When the keyring is unavailable, encryption throws — the service fails CLOSED and nothing is persisted as plaintext. A wrapped, user-actionable error message replaces the internal F065 jargon.
• Per-kind shape validation — the Zod schema for the credential's kind is parsed on create, on every secret-bearing update, and again on resolve as defense in depth against a corrupt or pre-schema blob.
• High-risk write-gate — checked in BOTH the IPC handler (so the error envelope is shaped by the handler, not the service) AND inside the service (so non-IPC callers can't bypass it). Both layers fail CLOSED on a missing setting flag.
• Secrets never cross IPC — listCredentialsMetadata returns id / kind / name / timestamps only, augmented in the handler with isHighRisk: boolean. The store carries that shape verbatim; the unit test cross-checks that JSON.stringify(state) doesn't contain a secret string after a create.

The Credential picker component at ../../src/renderer/src/features/automations/components/CredentialPicker.tsx is a read-only sibling of the settings panel — it never creates, edits, or deletes, only filters the store to its kind prop and renders the gated rows as disabled <option>s. The picker mirrors the IPC-level write-gate for visual feedback but never enforces it — the handler is the sole authority. The empty-state's Add credential button deep-links via navigateToSettingsProject({ section: 'automation-credentials' }).

Resolution happens at run start, never mid-run: the executor calls resolveCredential(id, { automationId, runId }), the service decrypts, JSON-parses, re-validates, and audit-logs the successful resolve to credential_access_log. Failed resolves are NOT logged — nothing usable was returned, so there's nothing to record as "accessed"; the thrown error lands in the automation run log instead.

Where this fits in the v2 automation flow

This page is the secrets-storage layer that the v2 action chain depends on. The integration-by-id model (action references credentialId, never the secret itself) is what lets credentials be rotated without editing every automation, and what keeps the inbox approval payload clean — when an external AI queues an automation create through the CLI server, the approval modal shows you the credentialId reference, not the secret. See automations-and-auto-replies.md for the full action-chain model, the cron-like / message / session-state triggers, and the per-rule preset catalog.

For agents

CLI GET routes — metadata only

External AI agents (via the omniscio-control skill) can enumerate credentials over the CLI control server. These routes return metadata only — the encrypted secret is never present in any response:

Method	Path	What it returns
GET	/automation/credentials	Array of all credentials: { id, kind, name, createdAt, updatedAt }
GET	/automation/credentials/:id	Single credential by id; 404 on unknown id

Use GET /automation/credentials to discover existing credential IDs before referencing one in an automation action. The id from this list is what you pass as credentialId in a cli_session or forward_email action chain.

Related

• automations-and-auto-replies.md — the parent feature; v2 actions reference credentials stored here
• cli-pending-actions.md — the approval queue an external AI uses; automation-rule creates ride on the separate per-row approval_status='pending' flag described there