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}`);
}