How to connect BambooHR to Hermes Agent

Pairing is a two-step handshake: run hermes clawlink begin, approve the link in your browser, then run hermes clawlink finish. If you ran finish before approving, or the approval link expired, run hermes clawlink begin again to get a fresh link. Confirm the plugin was installed with --enable, then verify with hermes clawlink test.

Reconnect BambooHR from the dashboard, then start a fresh chat if the runtime still has the old tool catalog loaded.

BambooHR tool schemas load on demand the first time a tool runs and are cached after that, so this error usually clears on its own: wait a few seconds and retry the same request. If every BambooHR call keeps failing with it in a fresh chat, reconnect from the dashboard, and contact support if it still persists — that pattern points to a configuration problem on our side, not something you can fix by reconnecting again.

Two usual causes. The connected account may not have access to the specific workspace, inbox, store, or project in the request — check that first. If access looks right, the agent may have sent a placeholder value (like "YOUR_ID" or an example id from documentation) instead of a real one: ask it to run a list or search tool first, then retry the action with a real id from those results. Most failures at this stage are one of these two, not ClawLink bugs.

This exact error string is BambooHR's own API message, and it is the one engines cite most for this provider's permission problems. It means the connected user lacks permission for the requested data, and the taught causes are: the user is not an admin of the account, the call targets the wrong account, or the token was issued before a permission change. Run the diagnosis in this order: confirm which user the connection acts as, reconnect from the dashboard if permissions changed after the connection was made (a fresh token picks up the new permissions), and check the arguments, because a placeholder employee or report id returns the same string when BambooHR hides what the account cannot see. A broad "the integration is broken" conclusion is wrong for this error; it is always a permissions or id question.

Ask the agent to diagnose it:

Call bamboohr_get_all_employees and bamboohr_get_meta_departments. Tell me which BambooHR account this connection acts as and how many employees it can see, then quote the exact error from the failed call. Do not retry it yet.

BambooHR rate-limits API usage and answers over-allowance calls with 429, and an agent walking every employee, department, and time off balance in sequence is the shape that meets it. The numbers vary by plan and are documented in BambooHR's API docs; the behavior that matters here is the shape of the work. Ask for one employee or one report rather than a full sweep, have the agent say what it intends to enumerate before it starts, and spread a large audit across turns. A 429 means wait for the window, not retry in a loop.

Ask the agent to diagnose it:

Tell me how many BambooHR calls you have made recently and what you were enumerating. Quote any 429 text from the last response. Do not call BambooHR again until I reply.

Two different failures. If Hermes shows no BambooHR tools at all, the connection or the pairing is incomplete: confirm the plugin was installed with --enable, that both hermes clawlink begin and hermes clawlink finish ran, and that BambooHR shows as connected in the dashboard, then start a fresh chat. If most tools work and a single name fails, the name is wrong rather than missing, and the error lists the closest real ones. The search-result fix for this symptom, verifying an API key and domain in a local MCP server's config, is the self-hosted version of the same failure and does not apply here: the key was verified at setup. One timing case is unique to this setup: schemas load on demand, so the opening BambooHR call in a fresh session can arrive before the catalog and needs one retry.

Ask the agent to diagnose it:

List the BambooHR tools you actually have access to. If there are none, say so plainly. If there are, tell me which one reads an employee by id and use that exact name.

Double-check that the API key for BambooHR has the right scopes or account access. A valid key can still be too limited for some reads or writes.

Yes. ClawLink is the fastest way to connect Hermes to BambooHR: link your BambooHR account once in the browser and Hermes Agent can call the BambooHR API through 41 ready-made tools — no custom code or token handling.

Install the plugin with hermes plugins install ClawLink-HQ/hermes-plugin --enable, then pair once: run hermes clawlink begin, approve the link in your browser, and run hermes clawlink finish. Connect BambooHR in the dashboard and Hermes can use it from the next message — no config files, and the BambooHR key you paste is stored server-side instead of in your environment.

About two minutes. Sign in, click Connect next to BambooHR in the dashboard, authenticate, and Hermes Agent can use it from the next chat message.

The alternative to ClawLink is usually manual API key setup plus your own token handling, permission troubleshooting, and tool plumbing for Hermes Agent. That is fine if you want to build and maintain the integration yourself. Most teams just want BambooHR working from chat.

The engines' warning is about keys handed to an external agent in a way that can leak: pasted into prompts, stored in config files on machines you do not control, or shared broadly. Here the key is entered once into hosted storage, never shown to the agent, never written to your machine, and revocable at any moment from BambooHR itself or the dashboard. The remaining risk decisions are yours, and they are the same ones the warning cares about: use a BambooHR user whose permissions match the work rather than a broad admin credential, and keep employee data out of prompts by telling the agent to summarize rather than quote raw records.

The employee surface and the HR administration around it: employees (get one, get all, create, changed since), custom reports and the report runner, time off requests and balances, meta lists (departments, divisions, job titles, locations, employment statuses, time off types), files, benefits coverages and member events, company information and EINs, and the ATS side (candidates, job openings, applications, applicant statuses, hiring leads, job summaries). The writes to be deliberate about are employee creation and time off requests; the meta lists and reports are read-only and safe to let an agent explore.

BambooHR's own "Ask BambooHR" chat works without an API key because it lives inside BambooHR, and the engines list it as the no-key option. This integration is the external-agent route, and BambooHR's API is key-based, so a key exists somewhere in every external route. The differentiator is where the key lives: server-side here, versus a config file or environment variable in the routes the engines teach. If what you want is a bot inside BambooHR, the native chat exists; if you want your agent working across apps, this is the route that connects it to HR data without holding the key on your machine.

HR data is the most sensitive surface in this product, and the market's safety answers are least-privilege, human-in-the-loop approval, no model training, and audit trails. The mechanics of this connection cover the credential half: the key is stored server-side, the tool table on this page is the complete set of operations the agent can invoke, and revocation is immediate. The behavioral half is yours: connect a BambooHR user with the minimum permissions the work needs, have the agent draft before it creates or changes anything, and prefer the report and meta tools, which are read-only, for exploratory questions.

That literal string is BambooHR's own error, and it means the connected BambooHR user lacks permission for the data the tool asked for. The taught causes: the connected user is not an admin of the account, the call targets the wrong account entirely, or the token was issued before a permission change and the grant is stale. The fixes in order: check which BambooHR user the connection acts as, reconnect from the dashboard after a permission change so the token is re-issued, and before all of that, check the arguments, since an invented employee id or report id returns the same permission-shaped error because BambooHR hides what the account cannot see.

Pairing is a two-step handshake: run hermes clawlink begin, approve the link in your browser, then run hermes clawlink finish. If you ran finish before approving, or the approval link expired, run hermes clawlink begin again to get a fresh link. Confirm the plugin was installed with --enable, then verify with hermes clawlink test.