Every external app you connect to Keragon as a tool inside an agent runs through the same authentication layer. When a run fails with an "auth" or "connection" error, it almost always falls into one of the patterns below — work through them in order before reaching out.
Beta note: This article covers the Keragon Agents early-access release. Behaviour, limits, and UI may change during the early access period; this page is updated on a rolling basis as we observe real failures with early adopters.
Heads up: Today, agents only surface authentication problems for a tool after you enter test mode. We're working on making auth status visible upfront so you don't run into this during a test. Until then, the checks below are how you confirm a connection is healthy.
How Keragon authentication works (quickly)
When you connect an app to Keragon, we store a connection record (a "connected account") that the platform uses for every call to that app. Two flavours:
- OAuth 2.0 (most common: Google Workspace, Salesforce, Zendesk, Square, HubSpot, etc.) — Keragon holds a refresh token and exchanges it for a fresh access token before each call. You authorise once; we keep it alive automatically.
- API key / Basic auth / Bearer token (Elation, OpenEMR, Availity, custom internal systems, etc.) — credentials you paste in once and we encrypt at rest.
Credentials are fetched fresh on every tool call, never cached in the agent, and never shown to the LLM. The agent only sees the tool — it never sees your token.
Refresher: A tool is one specific action your agent can take inside a connected app — for example Find a patient in Athena Health, Send a message to a Slack channel, or Create an appointment in Healthie. You attach tools to an agent when you build it; the agent decides which ones to call at runtime, based on your instructions.
Common authentication error codes
| Code | What it means | What to do |
|---|---|---|
| 401 Unauthorized | The token Keragon sent was rejected. Most common cause: an OAuth refresh token has been revoked (user removed the app, password was reset, or the upstream tenant rotated keys). | Open the connected account in Keragon, click Reconnect, and re-authorise. |
| 403 Forbidden | The token is valid but the account doesn't have permission for the specific action. Either the connected user lacks the scope/role, or the upstream admin has restricted the app. | Confirm the connected account has the right permissions in the source system. For OAuth apps, you may need to re-authorise with broader scopes. |
| 404 Not Found | The endpoint or resource ID the agent tried to reach doesn't exist for this account. Often a wrong sub-domain (e.g. a DrChrono subdomain typo) or a record that was deleted upstream. | Double-check any account-specific fields in the connection (subdomain, instance URL, region) and the record ID being passed in. |
| 429 Too Many Requests | You've hit the upstream app's rate limit. Common with Athena Health, HubSpot, and bulk syncs of patient or claims data. | Re-run after a short wait. If the agent is making many calls in a tight loop, see My agent is stuck in a loop in the Troubleshooting agents article — looping multiplies your rate-limit risk. |
| 500 / 502 / 503 / 504 | The upstream service is having problems — not Keragon, not your config. | Wait a few minutes and re-run. If the upstream system has a status page, check it. |
What to check, in order
Is the connection still connected?
Open the test panel and run your agent — if any tool is broken or needs re-authorisation, the agent will flag it. To reconnect, head to the Authentications tab in the left side panel, click your app, and hit Reconnect. Then follow the authentication steps the app provides. The example below shows the flow using Slack.
Was the account password recently changed upstream?
Password resets often invalidate OAuth grants. Reconnect to refresh the link.
Is the connected user still active in the source system?
If the user who originally authorised the connection was deactivated (e.g. an ex-employee in Google Workspace), every call from that connection will fail. Reconnect with an active user.
Are the scopes correct?
For OAuth apps where you can choose scopes during authorisation, a tool may need a scope you didn't grant. Reconnect and select the missing scope.
Is it the right account?
Multi-account orgs sometimes have several connections to the same app (e.g. two HubSpot portals). Make sure the agent's tool is pointed at the connection you intend.
Does your app need setup-specific credentials?
Some apps (Salesforce client ID & secret, Zendesk OAuth credentials, OpenEMR API access, etc.) need additional steps to configure correctly. Keragon has per-app credential guides in the help center — search the app name to find the right one.