Credentials

Credentials store API keys and secrets used by workflow nodes. You add them in the Credentials Tab and reference them by name in node configuration.

What Credentials Are

• Stored per user – Each credential belongs to a user and can be shared with other users or Teams.
• Encrypted at rest – Sensitive values are encrypted; the UI masks them after creation.
• Referenced by name – Nodes select a credential by name (or ID). The execution engine resolves the credential for the workflow owner at run time.

How Nodes Use Them

For detailed setup (hosts, ports, provider-specific fields), see Third-Party Integrations. That includes Telegram bot setup, inbound email via IMAP, and outbound email via SMTP.

GitHub credentials can also include an optional base_url when you are targeting GitHub Enterprise Server instead of GitHub.com. When you edit a GitHub credential to rotate the token, leaving base_url empty preserves the existing Enterprise endpoint. Enter a new URL only when you want to change that endpoint.

Jira, Linear, Supabase, Notion, Sentry, and ClickHouse credentials expose Test Connection in the credential dialog. For Jira, the check calls Jira's current user endpoint. For Linear, the check calls the Linear API with getViewer and confirms the API key or OAuth token is valid. When editing, you can test without re-entering the API key if the stored secret is still present. For Notion, choose Internal token or OAuth in the dialog; OAuth uses the Client ID and Client Secret from your Notion public integration. See Third-Party Integrations for Notion setup details.

Coding-package usage

The AI Defaults tab in Settings shows remaining coding-package usage for your Codex credentials (owned and shared). For each Codex credential it renders a horizontal bar per active rate-limit window — typically a 5 hours and/or Weekly window, depending on your plan — with the percentage of quota left and a reset countdown. The data comes from the Codex backend's rate-limit response headers, fetched on demand.

OpenCode Go credentials are listed there too, but marked "usage unavailable": the OpenCode zen gateway does not expose remaining-quota data, so no bar can be shown.

In Expressions

Some nodes allow expressions for auth. Use Expression DSL with $credentials.CredentialName to reference a credential's resolved secret inside an expression. For the header line each credential type needs in an HTTP request, see HTTP › Authenticating with Credentials.

Codex credentials are intentionally excluded from $credentials. Whether you sign in with ChatGPT (subscription, no per-token API cost) or paste a Codex access_token, the tokens are only passed to the local Codex runner process. ChatGPT sign-in tokens are refreshed automatically as they expire.

Jira credentials are also excluded from $credentials. The Jira node loads the credential by credentialId at run time. For custom Jira REST calls not covered by the Jira node, use the HTTP node with Jira Basic Auth (email:api_token for Jira Cloud or username:password for Data Center / Server), for example curl -u you@example.com:YOUR_API_TOKEN https://your-domain.atlassian.net/rest/api/3/myself. You can also use a Header credential with Authorization: Basic <base64(user:secret)>. Jira Data Center / Server personal access tokens and Bearer auth are not supported by the Jira credential yet.

Example:

$credentials.MyBearerToken
$credentials.MyNotionWorkspace

Use the Notion node for native database, page, and block operations. Use $credentials when a custom HTTP request needs the same Notion bearer token.

Creating Credentials from Chat

The AI Assistant, the Chat tab and Chat with Heym can create a credential when a workflow needs one, or whenever you ask for one. The assistant suggests the type and a name, and the regular credential form opens in the conversation. Ask to update a credential you own and the same form opens on it, with its secrets masked. The assistant only sees the name and type. heym_chat over MCP cannot create, update or choose credentials.

Related

• Credentials Tab – Add, edit, delete credentials
• GitHub Node – Native GitHub REST operations
• Jira Node – Jira project, issue, comment, attachment, user, notification, and transition automation
• Linear Node – Linear GraphQL workspace and issue automation
• Notion Node – Search and manage Notion content
• Sentry Node – Sentry organization, project, team, issue, event, and release automation
• Credentials Sharing – Share with users and teams
• Third-Party Integrations – Setup guide per credential type
• Expression DSL – $credentials in expressions

Model Router (Auto Model)

A Model Router holds no key. It holds a decision model credential, a list of model options — each an existing OpenAI, Google or Custom credential plus a model — and, for each option, free text saying when that option should be used.

It appears in every picker that offers a model: the LLM and Agent nodes, Chat, AI Defaults, Dashboards, the expression builder and Data Tables. Its only model is Auto. Pick it, and the decision model reads each request and routes it. Evals leaves it out, because an eval compares specific models and a router picks its own.

An agent re-routes as its tool loop progresses, so a cheap model can take the early turns and a stronger one the turn that needs it. Identical inputs reuse the previous decision, so a loop only pays for a decision when the conversation has actually moved.

What it cannot do

Auto Model cannot be combined with the Responses API, Batch mode, or image output. Those toggles disable themselves when a router is selected, and each says why. Guardrail checks and the human-review policy classifier are fixed single-model calls and never route.

When routing fails

Mark one option Use this option when routing fails and a decision model outage never stops a run; the fallback is used and the reason is recorded on the run. Without one, the node fails rather than guessing.

Seeing where a request went

Traces shows Auto Model / GPT-5 rather than the model alone, and cost stays attributed to the model that actually ran. The canvas Execution Log and Span View show the same pair, and the Span View lists which turn went where.