Third-Party Integrations

Heym connects to external services through credentials. Each credential type stores the connection details for one service and can be reused across multiple nodes and workflows. See Credentials for an overview.

Add credentials in Settings → Credentials. All values are encrypted at rest. Credentials can be shared with other users or Teams.

Some integration nodes do not require credentials. WebSocket Trigger and WebSocket Send connect to external sockets using the URL, headers, and subprotocols configured directly on the node.

Credential Types at a Glance

GitHub

The GitHub credential stores a GitHub personal access token (PAT) so workflows can call the GitHub REST API through the GitHub node, pass the token into MCP servers such as @modelcontextprotocol/server-github, or use it from the HTTP node for custom REST calls.

Required Fields

Optional Fields

Notes

• Fine-grained personal access tokens are recommended when possible because you can scope them to specific repositories and permissions.
• Leave base_url empty for GitHub.com. For GitHub Enterprise Server, use the full REST API endpoint including /api/v3 (for example https://github.example.com/api/v3), not the server's web UI root such as https://github.example.com.
• This credential currently models PAT-based auth only. To access organization repositories, use a PAT that has been granted the required organization/repository permissions.
• GitHub App installation tokens and GitHub App setup flows are not first-class in the Heym UI today.
• Prefer the GitHub node for native repository, user, issue, pull request, review, release, Actions workflow, traffic, and file operations. Use the HTTP node only when you need endpoints or payloads the GitHub node does not cover.
• Use the Agent node with MCP by passing $credentials.YourGitHubCredential into an MCP connection environment variable such as GITHUB_PERSONAL_ACCESS_TOKEN.
• GitHub's REST API commonly expects Authorization: Bearer <token> plus Accept: application/vnd.github+json.
• When editing a GitHub credential, leaving the GitHub Enterprise base_url empty preserves the existing endpoint. Enter a new URL only when you want to change that endpoint.

Used By

• GitHub node
• Codex node
• Agent node
• HTTP node

OpenAI Codex

The OpenAI Codex credential authenticates the Codex node. It is separate from the OpenAI API key credential used by LLM, Agent, and RAG nodes.

Authentication Modes

Notes

• API keys are rejected for this credential type.
• Codex tokens are not exposed through $credentials.Name.
• The Codex node also needs a GitHub credential for repository clone, branch push, and draft PR creation.

Used By

• Codex node

OpenCode Go

The OpenCode Go credential authenticates the OpenCode Go node. It stores an OpenCode Go gateway API key (from opencode.ai/go) and an optional gateway base URL.

Fields

Notes

• The API key is passed only to the OpenCode CLI process inside a hardened container.
• The OpenCode Go node also needs a GitHub credential for repository clone, branch push, and pull request creation. The GitHub token is never placed inside the sandbox container.

Used By

• OpenCode Go node

Linear

The Linear credential supports either a personal API key or OAuth2 for the Linear node. Heym sends native GraphQL queries to Linear for workspace metadata, projects, issues, and comments.

Setup

Choose one authentication mode:

Personal API key

1. In Linear, open Settings → Security & Access → Personal API keys.
2. Create a key with access to the workspace you want to automate.
3. Paste the key into a Linear credential in Heym and use Test Connection to verify it.

OAuth2

1. Create a Linear OAuth application.
2. Register {FRONTEND_URL}/api/credentials/linear/oauth/callback as the redirect URI.
3. In Heym Dashboard → Credentials → New → type Linear.
4. Choose OAuth2, enter the Client ID and Client Secret, then click Connect.

Required Fields

OAuth tokens (access_token, refresh_token, token_expiry) are stored and refreshed automatically.

Notes

• Personal API keys and OAuth tokens act as the Linear user who created or authorized them.
• Linear OAuth uses the scopes read,write,issues:create,comments:create.
• Use Test Connection in the credential dialog to verify the API key or OAuth token against the Linear API.
• Use List Teams and List Projects in the Linear node to discover UUIDs before creating or filtering issues.
• Use List Workflow States and List Team Members to discover state and assignee UUIDs for updates.
• Rotate an API key by editing the credential and entering the replacement value. If you rotate OAuth app secrets, reconnect the credential via Connect.

Used By

• Linear node

Jira

The Jira credential stores Jira Basic auth credentials, Jira site base URL, deployment mode, and optional REST API version for the Jira node. Use cloud for Jira Cloud or data_center for Jira Data Center / Server.

Setup

Jira Cloud

1. In Atlassian account settings, create an API token.
2. In Heym Dashboard → Credentials → New → type Jira.
3. Enter the Atlassian email, API token, and Jira site URL such as https://your-domain.atlassian.net.
4. Use Test Connection to verify the credential.

Jira Data Center / Server

1. Select Jira Data Center / Server as the deployment.
2. Enter the Jira username and password used for Basic auth.
3. Enter the Jira site URL, for example https://jira.example.com.
4. Use Test Connection to verify the credential.

Fields

Notes

• The Jira node sends issue descriptions and comments as Atlassian Document Format text documents for Jira Cloud REST API v3. Data Center / Server credentials send plain text.
• Data Center / Server currently supports username/password Basic auth only. Personal access tokens and Bearer auth are not supported yet.
• Attachment upload accepts base64 or data URL content and is subject to the platform file size limit (default 99 MB). Attachment download can return base64 content when enabled.
• User creation, deletion, and issue notification require the authenticated Jira account to have the relevant Jira site or organization permissions.
• Use List Projects, Search Issues, and List Transitions to discover project keys, issue keys, and transition IDs.
• For custom endpoints not covered by the Jira node, use the HTTP node with Jira Basic Auth (email:api_token for Cloud or username:password for Data Center / Server) in the cURL command, or a Header credential with the matching Authorization: Basic <base64(user:secret)> value.

See also:

• Jira node
• Credentials

Sentry

The Sentry credential stores an auth token for the Sentry node. Heym uses Sentry's REST API for organization, project, team, issue, event, and release operations.

Required Fields

Optional Fields

Notes

• Leave base_url empty for Sentry SaaS.
• Use Test Connection to confirm the token can list visible organizations.
• For custom REST calls, use $credentials.YourSentryCredential as the bearer token.

Used By

• Sentry node

Qdrant

Qdrant is an open-source vector database used for semantic search and RAG (Retrieval Augmented Generation).

Required Fields

Notes

• Qdrant collections are managed from the Vectorstores tab. Each vector store maps to a Qdrant collection.
• The RAG node uses a vector store (which references a Qdrant credential) — it does not reference the credential directly.
• If your Qdrant instance requires an API key, include it in the qdrant_host value or configure Qdrant accordingly; the current integration does not have a separate Qdrant API key field.
• Self-hosted Qdrant: use the official Docker image and expose port 6333.

Used By

• RAG node (via vector store)
• Vectorstores Tab

Custom Embeddings (RAG)

By default RAG embeddings come from OpenAI. A RAG: Custom Embeddings credential points at any OpenAI-compatible embeddings endpoint instead — Ollama, vLLM, Text Embeddings Inference, LM Studio, Together, or a hosted gateway — and names the vector store it writes into.

Required Fields

Notes

• Qdrant accepts any dimension count. Each collection is created at the width this credential declares, so the Dimensions field is freely editable.
• Postgres (pgvector) requires exactly 1536 dimensions. Its column is a fixed vector(1536), so the Dimensions field is pinned to 1536 and a credential declaring any other width is rejected at save time.
• Shortening for pgvector. When the store is Postgres, the dialog offers Ask the endpoint to return 1536 dimensions. This sends the dimensions request parameter, which models trained with Matryoshka representations (OpenAI text-embedding-3-*, nomic-embed-text-v1.5, jina-v3 and similar) honour by returning a shortened, still-meaningful vector. Endpoints that do not support the parameter reject the request, and endpoints that accept but ignore it produce a clear error naming the width actually returned. Heym never truncates vectors itself, because slicing the output of a non-Matryoshka model degrades retrieval quality silently. The option is not offered for Qdrant, which can size a collection to any width.
• Use Test Connection in the credential dialog to embed a probe string and see the width the model actually returns before you create a store.
• The dimensions request parameter is only sent to OpenAI itself, since most OpenAI-compatible servers reject unknown parameters. The model's native width is validated against the credential instead.
• The existing RAG: Qdrant + OpenAI and RAG: Psql + OpenAI credentials are unchanged and keep working.

Used By

• RAG node (via vector store)
• Vectorstores Tab

Postgres (pgvector)

Heym can also store vectors inside its own Postgres database using the pgvector extension — no external vector service required. Create a RAG: Psql + OpenAI credential and use it when creating a vector store, then pick Postgres (pgvector) in the RAG node's Database dropdown.

Required Fields

Notes

• No host/port is needed — vectors are written to Heym's own database; Heym never connects to a different database.
• Every RAG feature available with Qdrant (insert, search, metadata filters, Cohere reranking, cloning, sharing) works identically with the Postgres backend.
• Requires the vector extension. Heym keeps the official postgres:16 image unchanged (so existing data is never touched) and auto-installs the postgresql-16-pgvector package at startup — run.sh, deploy.sh, and run_e2e.sh all handle this. The install is non-fatal: if it cannot run (e.g. no network), Qdrant RAG keeps working and the Postgres backend stays inactive (the migration skips the table gracefully).
• If you run the published single-container image (ghcr.io/heymrun/heym) against your own external Postgres, that database must support the vector extension (Heym cannot install it into a database it does not manage). Without it, creating or uploading to a Postgres vector store returns a clear message and Qdrant RAG continues to work.

Used By

• RAG node (via vector store)
• Vectorstores Tab

Grist

Grist is a spreadsheet/database hybrid that supports structured data and formulas. The Grist credential allows Heym to read and write Grist documents.

Required Fields

Notes

• The Grist node requires the Document ID (from the Grist document URL) and Table ID in its configuration — these are not part of the credential.
• For self-hosted Grist, set server_url to your instance's domain.
• Column IDs in Grist use underscores (e.g. User_Name), not display labels. Use the listColumns operation to discover them.

Used By

• Grist node

Google Sheets (OAuth2)

The Google Sheets credential connects Heym to the Google Sheets API using an OAuth2 "Bring Your Own App" model. You supply a Google Cloud OAuth2 Client ID and Client Secret, then authorize access via a browser popup. Tokens are refreshed automatically in the background.

Setup

1. Open Google Cloud Console → APIs & Services → Library → search for and enable Google Sheets API.
2. Go to Credentials → Create Credentials → OAuth client ID → application type Web application.
3. Under Authorized redirect URIs add: https://your-heym-domain/api/credentials/google-sheets/oauth/callback
4. Copy the generated Client ID and Client Secret.
5. In Heym Dashboard → Credentials → New → type Google Sheets (OAuth2).
6. Enter the Client ID, Client Secret, and a name, then click Connect to open the Google consent popup and authorize access.

Required Fields

Tokens (access_token, refresh_token, token_expiry) are stored and refreshed automatically — you do not manage them directly.

Notes

• The OAuth2 consent screen requires the spreadsheets scope (https://www.googleapis.com/auth/spreadsheets).
• Heym uses the refresh token to obtain new access tokens before they expire (60-second safety buffer).
• If you rotate the Client Secret in Google Cloud Console, reconnect the credential via the Connect button.
• Production: Set backend FRONTEND_URL to the exact public URL users open in the browser (scheme + host, e.g. https://heym.example.com). Heym builds the Google OAuth redirect URI from this value only — it does not trust Origin or X-Forwarded-* headers (client-controlled). Register {FRONTEND_URL}/api/credentials/google-sheets/oauth/callback in Google Cloud Console.

Used By

• Google Sheets node

Google Drive (OAuth2)

The Google Drive credential connects Heym to the Google Drive API using the same OAuth2 "Bring Your Own App" model as Google Sheets. You supply a Google Cloud OAuth2 Client ID and Client Secret, then authorize access via a browser popup. Tokens are refreshed automatically in the background.

Setup

1. Open Google Cloud Console → APIs & Services → Library → search for and enable Google Drive API.
2. Go to Credentials → Create Credentials → OAuth client ID → application type Web application.
3. Under Authorized redirect URIs add: https://your-heym-domain/api/credentials/google-drive/oauth/callback
4. Copy the generated Client ID and Client Secret.
5. In Heym Dashboard → Credentials → New → type Google Drive (OAuth2).
6. Enter the Client ID, Client Secret, and a name, then click Connect to open the Google consent popup and authorize access.

Required Fields

Tokens (access_token, refresh_token, token_expiry) are stored and refreshed automatically — you do not manage them directly.

Scope

Google Drive requests the full Drive scope (https://www.googleapis.com/auth/drive).

This is required because the node operates on files you already own. The narrower drive.file scope only grants access to files the OAuth client itself created, which would make listFolderFiles, updateFile, removeFile, and removeFolder see nothing of your existing Drive.

Because you supply your own Client ID and Secret from your own Google Cloud project, the Google app-verification requirements for this scope apply to your project, not to Heym.

Notes

• Heym uses the refresh token to obtain new access tokens before they expire (60-second safety buffer).
• If you rotate the Client Secret in Google Cloud Console, reconnect the credential via the Connect button.
• Shared drives are supported — the node sets supportsAllDrives on every API call.
• Production: Set backend FRONTEND_URL to the exact public URL users open in the browser. Heym builds the Google OAuth redirect URI from this value only — it does not trust Origin or X-Forwarded-* headers. Register {FRONTEND_URL}/api/credentials/google-drive/oauth/callback in Google Cloud Console.
• See Credential Sharing before sharing this credential with a team.

Used By

• Google Drive node

BigQuery (OAuth2)

The BigQuery credential connects Heym to the Google BigQuery API using an OAuth2 "Bring Your Own App" model. You supply a Google Cloud OAuth2 Client ID and Client Secret, then authorize access via a browser popup. Tokens are refreshed automatically in the background.

Setup

1. Open Google Cloud Console → APIs & Services → Library → search for and enable BigQuery API.
2. Go to Credentials → Create Credentials → OAuth client ID → application type Web application.
3. Under Authorized redirect URIs add: https://your-heym-domain/api/credentials/bigquery/oauth/callback
4. Copy the generated Client ID and Client Secret.
5. In Heym Dashboard → Credentials → New → type BigQuery (OAuth2).
6. Enter the Client ID, Client Secret, and a name, then click Connect to open the Google consent popup and authorize access.

Required Fields

Tokens (access_token, refresh_token, token_expiry) are stored and refreshed automatically.

Notes

• The OAuth2 consent screen requires the BigQuery scope (https://www.googleapis.com/auth/bigquery).
• Production: Set backend FRONTEND_URL to the public URL. Register {FRONTEND_URL}/api/credentials/bigquery/oauth/callback in Google Cloud Console.

Used By

• BigQuery node

Supabase

The Supabase credential connects Heym to a Supabase project's PostgREST API so workflows can query and mutate Postgres-backed tables.

Required Fields

Notes

• The Supabase node talks to /rest/v1/<table> and supports operator filters (eq, neq, gt, gte, lt, lte, like, ilike, is, in, and related PostgREST operators) plus nested or / and logical groups.
• For write operations, prefer a key intended for trusted server-side use with the minimum required table permissions.
• Nodes can override the schema per step even if the credential defines a default schema.

Used By

• Supabase node

ClickHouse

The ClickHouse credential connects Heym to an external ClickHouse database over its HTTP interface so workflows can run SQL, CRUD, and count operations against OLAP tables.

Required Fields

Notes

• The ClickHouse node uses the official clickhouse-connect HTTP client and parameterizes filter and value bindings.
• update and remove map to ALTER TABLE ... UPDATE and DELETE FROM, which are asynchronous ClickHouse mutations; both require a filter.
• upsert performs an INSERT and assumes a ReplacingMergeTree table for merge-on-key behavior.
• Use Test connection in the credential dialog to verify reachability.

Used By

• ClickHouse node

Notion

The Notion credential supports either an internal integration token or a public-integration OAuth connection. OAuth lets each user authorize a Notion workspace from Heym instead of manually copying a token.

Required Fields

The OAuth callback stores access_token, auth_mode, workspace_id, workspace_name, and bot_id automatically. Any previous internal api_token is removed when OAuth completes. Register this redirect URI in Notion: {FRONTEND_URL}/api/credentials/notion/oauth/callback.

OAuth setup flow

1. Choose OAuth in the credential dialog, enter a name, Client ID, and Client Secret.
2. Click Connect and authorize the workspace in the Notion popup.
   • For a new credential, Heym creates the credential record when you click Connect.
   • Complete authorization in the popup, then click Save to return to the credentials list.
3. A connected credential shows connected (Workspace Name) in the list. Pending OAuth credentials show Not connected until authorization finishes.

Use Test Connection in the credential dialog to verify either an internal token or a completed OAuth authorization. When editing, leaving the token field blank preserves the stored internal token.

Both internal tokens and OAuth access tokens are available through $credentials.CredentialName for custom HTTP calls that need a Notion bearer token.

Notes

• Internal integrations require the relevant pages, databases, and data sources to be shared.
• OAuth users choose the workspace/pages during Notion authorization.
• OAuth application credentials are encrypted inside the Notion credential. The callback reloads them server-side; the secret is not embedded in OAuth state.
• Connected OAuth credentials display the workspace name; pending OAuth credentials show Not connected until authorization completes.
• Production: Set backend FRONTEND_URL to the public browser URL (scheme + host, no trailing slash). The Notion redirect URI must match exactly: {FRONTEND_URL}/api/credentials/notion/oauth/callback.
• The node uses API version 2026-03-11 and current data_source terminology. See the Notion node article for migration guidance from older archived, after, or database-query examples.
• Old search filters with object value database are normalized to data_source.

Used By

• Notion node

SMTP (Email)

The SMTP credential stores email server connection details for sending outgoing mail.

Required Fields

Common SMTP Providers

Notes

• Gmail requires an App Password instead of your regular password when 2-Step Verification is enabled.
• Port 587 uses STARTTLS (starts plaintext, upgrades to TLS). Port 465 uses implicit TLS (SSL from the start).

Used By

• Send Email node

IMAP (Inbound Email)

The IMAP credential stores connection details for monitoring an inbox with the IMAP Trigger node.

Required Fields

Optional Fields

Notes

• The IMAP trigger baselines the current mailbox on first poll and then only processes newer email.
• Gmail, Microsoft 365, and other hosted providers often require an app password or similar IMAP-specific secret.
• Attachment content is not downloaded into the workflow payload; Heym exposes attachment metadata only.

Used By

• IMAP Trigger node
• Triggers (IMAP as workflow trigger)

RabbitMQ

RabbitMQ is an open-source message broker. The RabbitMQ credential stores connection details for publishing to and consuming from queues and exchanges.

Required Fields

Virtual Hosts

To connect to a specific virtual host, include it in the rabbitmq_host URL:

amqp://username:password@hostname:5672/vhost

If using the default vhost, the path / can be omitted.

Delayed Message Plugin

The RabbitMQ node supports the rabbitmq_delayed_message_exchange plugin. When this plugin is enabled on your RabbitMQ server, you can set a delay (in milliseconds) on outgoing messages using the rabbitmqDelayMs field on the node.

The node sets the x-delay header on the published message. The exchange type must be x-delayed-message for delays to take effect.

To enable the plugin on a self-hosted RabbitMQ instance:

rabbitmq-plugins enable rabbitmq_delayed_message_exchange

When the plugin is not installed, the x-delay header is ignored and messages are delivered immediately.

Used By

• RabbitMQ node
• Triggers (RabbitMQ as workflow trigger)

Amazon S3

The Amazon S3 credential connects Heym to Amazon S3. Use it with the Amazon S3 node to manage buckets and folders, upload and download objects, copy keys, and list or delete objects from workflows.

Required Fields

Optional Fields

Notes

• The credential uses standard AWS SigV4 authentication via boto3.
• Upload operations currently send UTF-8 text content; downloads can return text or base64 for binary objects.

Used By

• Amazon S3 node

Redis

Redis is an in-memory key-value store used for caching and fast data access.

Required Fields

Used By

• Redis node

Slack

The Slack credential stores an Incoming Webhook URL for posting messages to Slack channels.

Required Fields

Notes

• Create an Incoming Webhook at api.slack.com/apps → your app → Incoming Webhooks.
• Each webhook is scoped to a specific channel. Create multiple credentials for different channels.

Used By

• Slack node

Telegram

The Telegram credential stores a Bot Token and an optional Webhook Secret Token for bot-based workflows.

Required Fields

Optional Fields

Notes

• Use the same credential for both Telegram Trigger and Telegram.
• Register the webhook manually with Telegram's setWebhook API using the URL shown in the Telegram Trigger node panel.
• chatId in the Telegram node can be a literal ID or an expression like $telegramEvent.message.chat.id.

Used By

• Telegram Trigger node
• Telegram node

HTTP Auth (Bearer & Header)

These credentials are used by the HTTP node to authenticate outgoing requests.

Bearer

Attaches an Authorization: Bearer <token> header to HTTP requests.

Header

Attaches a custom header to HTTP requests.

Both types can also be referenced via $credentials.CredentialName in the Expression DSL for dynamic use in any node that accepts expressions.

Used By

• HTTP node

LLM Providers (OpenAI, Google, Custom, Cohere)

These credentials power AI nodes.

OpenAI Prompt Caching

OpenAI automatically caches the static (unchanging) prefix of your system prompt — no extra configuration required. Repeated workflow runs that share the same system prompt prefix benefit from cached token pricing, which reduces both cost and latency. This is especially useful when you have long, fixed instructions and only the user message changes between runs. Monitor cache hit rates and token savings in the Traces tab or the OpenAI usage dashboard to optimize your prompt structure for maximum cache reuse.

Used By

• LLM node
• Agent node
• RAG node (OpenAI embeddings via Qdrant credential)

FlareSolverr

FlareSolverr is a proxy server for bypassing Cloudflare and similar bot-protection challenges.

Required Fields

Used By

• Crawler node

Related

• Credentials – Overview of credentials and how nodes use them
• Credentials Tab – Add and manage credentials
• Credentials Sharing – Share credentials with users and teams
• Security – Encryption at rest, access control
• Expression DSL – $credentials syntax for dynamic access