HeartBeatAgents

An Integration Won't Connect

View as Markdown

What a specific connection error actually means, from a rejected API key to an unverified domain, and how to fix it.

"Invalid API key: authentication rejected by remote service"

The key itself was rejected by the service you're connecting to, not by HeartBeatAgents. Regenerate the key on that service's own site and try again; a copy/paste error (a trailing space, a truncated key) is the most common cause.

"Domain is not verified"

Some services (email senders in particular) only let you use a domain you've already verified on their side. Verify the domain in that service's own dashboard first; the error names which domains are already verified, if any, so you can confirm you're pointed at the right one.

"Please fill in both Client ID and Client Secret"

For a custom OAuth app, both fields are required before the connect flow can start; a service description with only a client ID (or only a secret) can't authenticate.

Connection times out, or "Cannot connect to {host}"

This is a network reachability problem to that specific host, not an authentication problem. Confirm the host is actually correct (a typo in a custom integration's API host is a common cause) and reachable from wherever this instance runs.

"Session expired: please log in again"

This interrupts an OAuth flow specifically, not your HeartBeatAgents session generally. Start the connection again from Settings → Integrations.

The connection test passes, but the integration still doesn't work for an agent

A successful test only confirms the credential itself is valid; it doesn't confirm an agent has been given access. Check Settings → Integrations → [that service] → Assign to agents to confirm the agent you expect is actually bound to it.