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

# 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

# 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:

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:

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:

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
• BambooHR Authentication Docs
• BambooHR API Technical Overview

Next Steps

After successful auth, proceed to bamboohr-hello-world for your first employee data retrieval.