--- name: bamboohr-install-auth-567bd9599106 description: | Install and configure BambooHR API authentication with HTTP Basic Auth. Use when setting up a new BambooHR integration, configuring API keys, or initializing BambooHR REST API access in your project. Trigger with phrases like "install bamboohr", "setup bamboohr", "bamboohr auth", "configure bamboohr API key", "bamboohr credentials". allowed-tools: Read, Write, Edit, Bash(npm:*), Bash(pip:*), Bash(curl:*), Grep version: 1.0.0 license: MIT author: Jeremy Longshore tags: [saas, hr, bamboohr, authentication] compatible-with: claude-code --- # BambooHR Install & Auth ## Overview Set up BambooHR REST API authentication. BambooHR uses HTTP Basic Authentication — your API key is the username, and the password can be any arbitrary string (typically `x`). **Base URL pattern:** ``` https://api.bamboohr.com/api/gateway.php/{companyDomain}/v1/ ``` Where `{companyDomain}` is your BambooHR subdomain (e.g., `acmecorp` from `acmecorp.bamboohr.com`). ## Prerequisites - Node.js 18+ or Python 3.10+ - BambooHR account with API access enabled - API key generated from BambooHR (Account > API Keys) - Company subdomain from your BambooHR URL ## Instructions ### Step 1: Generate an API Key 1. Log in to BambooHR at `https://{companyDomain}.bamboohr.com` 2. Click your profile icon > **API Keys** 3. Click **Add New Key**, give it a descriptive name 4. Copy the key immediately — it is only shown once ### Step 2: Configure Environment Variables ```bash # Required export BAMBOOHR_API_KEY="your-api-key-here" export BAMBOOHR_COMPANY_DOMAIN="yourcompany" # Create .env file for local development cat > .env << 'EOF' BAMBOOHR_API_KEY=your-api-key-here BAMBOOHR_COMPANY_DOMAIN=yourcompany EOF # IMPORTANT: Add to .gitignore echo '.env' >> .gitignore echo '.env.local' >> .gitignore ``` ### Step 3: Install HTTP Client ```bash # Node.js — no BambooHR-specific SDK needed; use fetch or axios npm install dotenv # Python pip install requests python-dotenv ``` ### Step 4: Verify Connection **TypeScript / Node.js:** ```typescript import 'dotenv/config'; const COMPANY = process.env.BAMBOOHR_COMPANY_DOMAIN!; const API_KEY = process.env.BAMBOOHR_API_KEY!; const BASE_URL = `https://api.bamboohr.com/api/gateway.php/${COMPANY}/v1`; // BambooHR uses HTTP Basic Auth: API key as username, "x" as password const headers = { 'Authorization': `Basic ${Buffer.from(`${API_KEY}:x`).toString('base64')}`, 'Accept': 'application/json', }; // Test: fetch the employee directory const res = await fetch(`${BASE_URL}/employees/directory`, { headers }); if (res.ok) { const data = await res.json(); console.log(`Connected. ${data.employees?.length ?? 0} employees found.`); } else { console.error(`Auth failed: ${res.status} ${res.statusText}`); const errHeader = res.headers.get('X-BambooHR-Error-Message'); if (errHeader) console.error(`Detail: ${errHeader}`); } ``` **Python:** ```python import os, requests from dotenv import load_dotenv load_dotenv() COMPANY = os.environ["BAMBOOHR_COMPANY_DOMAIN"] API_KEY = os.environ["BAMBOOHR_API_KEY"] BASE_URL = f"https://api.bamboohr.com/api/gateway.php/{COMPANY}/v1" # HTTP Basic Auth: API key as username, "x" as password response = requests.get( f"{BASE_URL}/employees/directory", auth=(API_KEY, "x"), headers={"Accept": "application/json"}, ) if response.ok: data = response.json() print(f"Connected. {len(data.get('employees', []))} employees found.") else: print(f"Auth failed: {response.status_code}") print(response.headers.get("X-BambooHR-Error-Message", "")) ``` **Quick curl test:** ```bash curl -s -u "${BAMBOOHR_API_KEY}:x" \ "https://api.bamboohr.com/api/gateway.php/${BAMBOOHR_COMPANY_DOMAIN}/v1/employees/directory" \ -H "Accept: application/json" | head -c 200 ``` ## Output - Environment variables configured (`BAMBOOHR_API_KEY`, `BAMBOOHR_COMPANY_DOMAIN`) - `.env` file created and git-ignored - Successful API response from `/employees/directory` ## Error Handling | HTTP Status | Header | Cause | Solution | |-------------|--------|-------|----------| | 401 | `X-BambooHR-Error-Message` | Invalid or missing API key | Regenerate key in BambooHR dashboard | | 403 | `X-BambooHR-Error-Message` | Key lacks permissions for endpoint | Use an admin-level API key | | 404 | — | Wrong company domain in URL | Verify subdomain matches `{x}.bamboohr.com` | | 503 | `Retry-After` | Rate limited or service unavailable | Wait for `Retry-After` seconds and retry | ## Enterprise Considerations - **Key rotation**: Generate a new key, update env vars, verify, then delete the old key - **Audit trail**: Each API key is tied to a user; BambooHR logs which key made each request - **IP allowlisting**: BambooHR does not support IP restrictions on API keys - **SSO/OAuth**: BambooHR supports OpenID Connect for browser login, but API access requires API keys - **Multi-tenant**: Store per-company credentials in a secrets manager (AWS Secrets Manager, GCP Secret Manager, Vault) ## Resources - [BambooHR API Getting Started](https://documentation.bamboohr.com/docs/getting-started) - [BambooHR Authentication Docs](https://documentation.bamboohr.com/docs) - [BambooHR API Technical Overview](https://documentation.bamboohr.com/docs/api-details) ## Next Steps After successful auth, proceed to `bamboohr-hello-world` for your first employee data retrieval. --- Source attribution: Jeremy Longshore Original project: https://github.com/aibot88/sec_skill_store/blob/608120788167d56f99e31449e411e603ed250dc6/skills/claudskills/bamboohr-install-auth/SKILL.md License: MIT License information: https://opensource.org/license/mit Original upstream instructions; downloaded from Mega AI Hub. ## Upstream license notice MIT License Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. # Mega AI Hub resource metadata Creator / publisher: Jeremy Longshore Original project: https://github.com/aibot88/sec_skill_store/blob/608120788167d56f99e31449e411e603ed250dc6/skills/claudskills/bamboohr-install-auth/SKILL.md Attribution basis: Source repository record Fields of work: Human Resources, Sales Roles: HR Generalist, Business Development, Customer Success Manager Specialties: API Tools: Bamboohr Country applicability: Country not specified Classification basis: Source category, role and specialization labels Instruction SHA-256: 5438663144fe0a2bba39a8117e2896c6ce240546dbff6261afaf2f1f7fb11bb2