BambooHR
HR system of record: agents read the employee directory, time off and reports through BambooHR's API.
Connect it with: API key. BambooHR's own documentation: https://documentation.bamboohr.com/docs/getting-started.
What agents can do
Connect BambooHR so the agents working your tasks can reach it. With it connected, they can:
- Look up people in the employee directory: names, job titles, departments, managers and work contact details.
- Read who is out and upcoming time off, for planning work around absences.
- Run your saved custom reports and summarize headcount, tenure or turnover.
- Read the fields and tables your account exposes, so tasks can map BambooHR data to other systems.
Before you start
- A BambooHR account whose access level is allowed to create API keys (ask your BambooHR admin if API Keys is missing from your menu).
- Your company domain - the subdomain in your BambooHR address.
- A Jaah account. Anyone can add a personal secret; an organization secret needs an Org Owner or Admin.
Connect with BambooHR
Jaah connects to BambooHR with an API key, not with a sign-in button.
Connect with an API key
Find each value first:
- Company domain: The first part of the address you sign in at: for https://acme.bamboohr.com it is acme.
- API key: In BambooHR, select your name or photo in the lower-left corner, choose API Keys, select Add New Key, name it Jaah and select Generate Key. Copy the key - BambooHR shows it once. The menu item appears only if your access level allows API keys.
Then add it to Jaah:
- In Jaah, open Secrets, select New, and pick the BambooHR card.
- Name the secret and choose who can use it.
- Fill in Company domain, API key.
- Select Save. Jaah tests the secret straight away (see Test the connection).
Jaah encrypts what you type and never shows it again — not to you, and not to an admin.
Use your own OAuth app
Not used: Jaah connects to BambooHR with an API key, not through an OAuth app.
Test the connection
Select Test on the secret. Jaah calls BambooHR's API once (GET https://<Company domain>.bamboohr.com/api/v1/employees/0?fields=displayName,firstName) with the stored values, and shows who it answered as, or which value BambooHR refused and the status it answered. Jaah also tests automatically when you save or reconnect.
The last result and its time stay on the secret's page, so you can see whether it still works without testing again.
Who can use it
Every secret has an owner, and the owner decides who can use it:
- Personal — only your own tasks can use it. This is the default.
- Organization — every task in the organization can use it. Only Org Owners and Admins can choose this.
- Attached to a project — every task on that project can use it, whoever started the task. See Attach a secret to a project.
More on owners and access: How secrets work.
Use it in an agent session
An agent asks for the secret with its credential_get tool, by the secret's path, when it needs it, and gets the values for that one call. The path is the owner's prefix and the secret's name:
org/<name>for an organization secret,projects/<project>/<name>for one attached to a project,me/<name>for your personal one.
A key connection hands the agent its fields: company_domain, api_key.
Tell the agent in your task description which secret to use, for example “use the BambooHR secret org/bamboohr”.
Manage, rotate or disconnect
Everything is on the secret's page under Secrets:
- Rotate a key: create a new key at the vendor first, then select Replace on the secret and paste it. Revoke the old key at BambooHR once the test passes. Steps: Replace or delete a secret.
- Disconnect: select Delete. The stored values are destroyed and agents lose access on their next call. To end access at BambooHR's side too, revoke or delete the key at BambooHR.
Limitations
- An API key acts with exactly the access level of the BambooHR user who created it: agents see only the fields and employees that user can see.
- BambooHR offers no read-only key: if the user can edit records, so can agents using the key. Create the key on a user with a restricted access level when agents should only read.
- BambooHR blocks a key for a while after repeated failed requests with a bad key, so fix a rejected key before testing again.
- Agents can do only what the connected BambooHR account allows.
Troubleshooting
Test says BambooHR rejected the API key (401 or 403)
The key was mistyped, revoked, or belongs to a user who has since been disabled or lost API access. Create a new key from your name > API Keys and select Replace on the secret. After several bad attempts BambooHR blocks the key briefly: wait a few minutes before testing again.
Test says BambooHR cannot be reached at that address
Company domain must be only the subdomain (acme), not the full address and not your email domain. Check the address bar when you are signed in to BambooHR.
The test passes, but an agent finds fields or employees missing
The key sees only what its user's access level allows. Ask a BambooHR admin to widen that user's access level under Settings > Access Levels, or create the key on a user who already has it.
Still stuck? Select Test and read the result: it names the value BambooHR refused and the status it answered.
FAQ
Which user should create the key?
A dedicated BambooHR user with the narrowest access level that still covers what agents need. Everything agents do is then attributed to that user, and disabling it ends their access.
How do I revoke the key in BambooHR?
Select your name > API Keys and delete the Jaah key. Agents lose access on their next call.
Can Jaah or an admin see the key or token?
No. Jaah stores it encrypted and never shows it again. Only the tasks allowed to use the secret receive it, at the moment they ask for it.
Can I connect more than one BambooHR account?
Yes. Add one secret per account, each with its own name, and tell the agent which one to use.