# BambooHR setup for PopMCP

You end up with two values: your BambooHR company subdomain, the part before .bamboohr.com, and a personal API key shown once when you generate it.

- Auth: API credentials
- Setup time: 3 min
- API base URL: https://{subdomain}.bamboohr.com/api/v1
- Credentials screen: https://YOUR-SUBDOMAIN.bamboohr.com/settings/permissions/api.php (replace YOUR-SUBDOMAIN with your BambooHR subdomain)
- Provider docs: https://documentation.bamboohr.com/docs/getting-started

## Before you begin

- A BambooHR user account with the API Keys option in the user menu, which is permission-gated
- An admin to generate the key if PopMCP needs full employee, payroll or time-off data, because a key inherits the creating user's permissions exactly
- Your company subdomain from the login URL, for example acme in `https://acme.bamboohr.com`

## Get your credentials

### 1. Note your company subdomain

Read the address bar while signed in to BambooHR. In `https://acme.bamboohr.com`, the acme part is what goes in PopMCP's Company subdomain field.

### 2. Open API Keys from your user menu

Click your name in the lower-left corner of any page, then choose API Keys. Account owners can also reach the full list at Settings > Account > API Keys.

### 3. Add a new key and generate it

Click Add New Key, type `PopMCP` into API Key Name, then click Generate Key.

### 4. Copy the key

Click COPY KEY in the confirmation dialog.

### 5. Paste both values into PopMCP

Put the subdomain in Company subdomain and the key in API key, then save the connection.

## Fields PopMCP asks for

- Company subdomain (subdomain) [required]: The first part of your BambooHR URL: https://<your-company>.bamboohr.com. You can paste the full URL; we'll extract the subdomain. This is the company the MCP is locked to.
- API key (apiKey) [required]: In BambooHR click your name in the lower-left corner of any page → API Keys → Add New Key. Copy it immediately (it's shown only once). The key inherits your permissions and is sent as HTTP Basic auth. Stored encrypted; used server-side only.

## Verify

PopMCP shows the BambooHR connection as Connected and an employee-directory call returns your real roster rather than a 401 or 403.

## Troubleshooting

### 401 Unauthorized

Cause: The key was mistyped, or the subdomain does not match the account the key belongs to.

Fix: Check the subdomain against your login URL and generate a fresh key. Keys are per-company and are not portable.

### 403 Forbidden and it was working before

Cause: BambooHR temporarily disables access when an unknown or invalid key is retried repeatedly.

Fix: Stop calling, wait for the block to lapse, then reconnect with a valid key.

### Some employees or fields are missing

Cause: The key inherits the permissions of the person who generated it.

Fix: Have an admin generate a replacement key and reconnect PopMCP with it.

### I closed the dialog without copying the key

Cause: BambooHR never redisplays a key value after generation.

Fix: Delete the unused key from the API Keys list and add a new one, copying it straight away.

### No API Keys entry in the user menu

Cause: Your BambooHR role does not include API key permission.

Fix: Ask an account owner to grant it, or to generate the key for you.

---

Source: https://www.docs.popmcp.com/docs/integrations/bamboo-hr/