---
title: An Integration Won't Connect
summary: What a specific connection error actually means, from a rejected API key to an unverified domain, and how to fix it.
date: 2026-09-10
---

# An Integration Won't Connect

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.

## Related

- [Integrations Guide](/en/docs/guides/integrations-guide): how connecting a service is supposed to work
- [Custom Integrations](/en/docs/guides/custom-integrations): the verification step for a self-defined integration specifically
- [Agent Stuck in a Retry Loop](/en/docs/troubleshooting/agent-stuck-retry-loop): when a previously-working integration starts failing mid-conversation