Integrations and credentials

Integrations are catalog entries per workspace. Connecting them stores a workspace-scoped credential (encrypted) and marks the integration connected. Secrets you type in Settings → Secrets are the same credential records.

Settings surfaces

The app uses tRPC settings.listIntegrations / updateIntegration and settings.listCredentials / createCredential (also session REST /api/integrations and /api/credentials).

Catalog and connection

GET /api/v1/integrations returns { integrations[] } for the API key's workspace: key, name, category, description, status (available or connected), optional credentialId / credentialName / credentialType, credentialConfigured, connectedCredentials[], timestamps.

PATCH with { key, connected } upserts the connection row. Unknown keys return 400 "Unknown integration.".

When connected is true and credentialValue is present, the server creates or updates a workspace credential (type derived from the integration) and returns { integration, credential } with maskedValue (never the plaintext). Multiple named credentials can exist for one key (for example two Gmail accounts).

Supported OAuth keys include github, google-workspace, google-drive, gmail, jira, microsoft-teams, and others in integrationOAuthProviders. Start returns { authorizationUrl, provider, credentialName, expiresAt } and sets an OAuth state cookie, or 200 with missingConnectorSetup / mode: "manual" when client env is incomplete. Callback writes the token into a credential and redirects to returnTo (default Settings → Integrations). returnTo must be a safe internal path.

Gmail and Trash

Gmail connections request gmail.modify, which supports reading, sending, organizing mail and moving it to Trash. The Google Workspace connection uses the same Gmail permission alongside its other service permissions.

Use Move message to Trash or Move thread to Trash in a Gmail block. The thread action moves all messages in that conversation. You can restore mail from Trash in Gmail while it remains there. These actions retain their confirmation requirement.

Existing saved workflows and imported n8n Gmail Delete actions now move mail to Trash too. Their operation IDs remain delete-message and delete-thread. Successful outputs include trashed: true; the older deleted: true field remains for compatibility and means the move succeeded.

Existing connections with full Gmail access remain usable. Requesting a smaller scope does not remove an earlier Google grant. To grant only the currently requested permissions, remove the app's existing access in your Google Account, then reconnect the affected services in Integrations. Removing a shared grant can disconnect other services that use it.

Using your own OAuth Client ID and Client Secret still requires Google consent. Google's unverified-app warning depends on the OAuth application's verification status and requested permissions.

The individual Docs connection requests document access only. Calendar requests calendar discovery, event management and availability permissions; it does not request permission to manage sharing or delete calendars. Existing full Calendar grants remain usable. Older event-only connections must reconnect before using Check availability.

In production, new Google consent is limited to reviewed permissions or a configured verification audience. A 403 with google-oauth-verification-required means the deployment administrator must finish that setup; repeatedly reconnecting or pasting a different client secret will not clear it. The verification audience is checked again when Google redirects back. Saved connections continue to use their recorded grants.

Copy and move Drive files; replace text in Docs

Select a Google Drive or Google Workspace connection for Copy file and Move file. Both use fileId for the source file. Set parentFolderId to the destination folder; it is required for Move file and optional for Copy file. Copy file also accepts an optional name for the new file. Open the result in Drive to check its name and location.

For Google Docs Replace all text, select a Docs or Google Workspace connection, enter documentId, and add replacements entries with search and replace. An empty replace removes the matching text. For example, [{"search":"BEFORE","replace":"AFTER"}] replaces every occurrence of BEFORE. Open the document to verify the change. These actions use the existing Drive and Docs permissions.

Imported workflows can also use the older folderId, fileName, text, and replaceText fields. Non-blank older destination, name, and search values take precedence; if they render as empty or whitespace, the fields above are used. An empty replaceText still removes matching text, even when replace is also present.

Create a Google Sheets tab

In the workflow builder, add Google Sheets: Create sheet to create a tab inside an existing spreadsheet.

1. Select your Google Sheets or Google Workspace connection.
2. Choose the existing spreadsheet or enter its spreadsheetId from its Google Sheets URL.
3. Set title to the new tab name, then test the block.
4. Open the returned url to check the new tab. Use the returned sheetId in later blocks that need a tab identifier; use the tab title in A1 ranges for reading or writing cells.

The action returns spreadsheetId, sheetId, title, index, and url. Create spreadsheet creates a separate file; Create sheet adds a tab to the selected file. This uses the existing spreadsheets permission and requires no additional OAuth permission.

A duplicate tab name produces a Google error; choose another name. The action does not retry automatically. If a request times out, check the spreadsheet before running it again, because Google may already have created the tab.

Credentials and secrets

For workflow Versions & previews, choose compatible connections explicitly for each destination. Each field filters by provider and required permissions. Add credential opens the existing provider dialog without leaving the deployment setup; save and test a workspace credential, then save the destination’s connection choices. OAuth sign-in returns to the same destination, where you can select the connected account. Production and a preview can share an AI connection while using different CRM accounts. A shared account still reaches the same real data; a separate preview URL does not isolate that account. AIMS approval covers the exact destination and connection references. Rotated secret values are resolved when executing, while missing, inaccessible or retired connections block execution. Creating a preview does not copy provider subscriptions, mailbox cursors or pinned test data. External secret-provider references from the former environment catalog are not automatically converted into workflow connections.

Values are encrypted with AES-256-GCM (APP_ENCRYPTION_KEY, or a dev-only default). List/create/update responses expose maskedValue (•••••••• from Prisma mapping). OAuth scope strings may be parsed from JSON secrets into oauthScopes.

Create requires name and type. Optional envVar is not an arbitrary environment variable: it must be a known deployment source (DATABASE_URL, GITHUB_TOKEN, OPENAI_API_KEY, SMTP/Google/Jira/Microsoft/Supabase JSON, etc.) whose type matches the credential. Otherwise the API returns a public error and does not store the secret.

Claude Code / Codex CLI types (claudeCodeOAuth, codexCliSession, or those display names) cannot be created or patched through credentials REST/tRPC. Use the local AI CLI worker login on Settings → Workers.

POST /api/v1/credentials/{id}/test decrypts the secret and runs testCredentialConnection. Unlike list/create/update/delete, the test route does not require workspace-scoped keys — any valid bearer key for that workspace id can test.

Personal credentials: tRPC createCredential accepts scope: "personal" and binds userId. The v1 REST create path always stores scope: "workspace".

Authorization

There is no Admin/Owner check on credential CRUD. Cross-workspace ids return 403/404.

Failure modes

• Invalid type/value format: 400 from validateCredentialSecretValue.
• Duplicate name for the same scope: create updates the existing row instead of erroring.
• Decrypt failure at test/runtime: SecretDecryptionError — reconnect the credential.
• OAuth start without key: 400. Foreign workspaceId: 403.

Next steps