BambooHR Security Basics

Overview

Security best practices for BambooHR API integrations covering API key management, webhook HMAC verification, PII handling, and access control. BambooHR contains highly sensitive employee data (SSNs, salaries, addresses) — treat every integration as PII-critical.

Prerequisites

• BambooHR API access configured
• Understanding of environment variables and secrets management
• Access to BambooHR admin settings

Instructions

Step 1: API Key Security

# .env (NEVER commit to git)
BAMBOOHR_API_KEY=your-api-key
BAMBOOHR_COMPANY_DOMAIN=yourcompany
BAMBOOHR_WEBHOOK_SECRET=your-webhook-hmac-secret

# .gitignore — MUST include these
.env
.env.local
.env.*.local
*.pem

Key management rules:

• Each environment (dev/staging/prod) uses a separate API key
• Create API keys under service accounts, not personal accounts
• API keys inherit the permissions of the user who created them
• Rotate keys quarterly; immediately rotate if exposed

Key rotation procedure:

# 1. Generate new key in BambooHR: Profile > API Keys > Add New Key
# 2. Update secret store
aws secretsmanager update-secret --secret-id bamboohr/api-key --secret-string "new-key"
# Or for GCP:
echo -n "new-key" | gcloud secrets versions add bamboohr-api-key --data-file=-

# 3. Deploy with new key
# 4. Verify new key works
curl -s -o /dev/null -w "%{http_code}" \
  -u "new-key:x" \
  "https://api.bamboohr.com/api/gateway.php/${DOMAIN}/v1/employees/directory" \
  -H "Accept: application/json"

# 5. Delete old key in BambooHR dashboard

Step 2: Webhook Signature Verification

BambooHR signs webhook payloads with SHA-256 HMAC. Verify every webhook before processing.

import crypto from 'crypto';

function verifyBambooHRWebhook(
  rawBody: Buffer | string,
  signature: string,
  timestamp: string,
  secret: string,
): boolean {
  // 1. Reject old timestamps (replay attack protection — 5 min window)
  const age = Date.now() - parseInt(timestamp, 10) * 1000;
  if (age > 300_000 || age < -60_000) {
    console.error(`Webhook timestamp outside 5-minute window: ${age}ms`);
    return false;
  }

  // 2. Compute expected HMAC
  const payload = `${timestamp}.${rawBody.toString()}`;
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');

  // 3. Timing-safe comparison (prevents timing attacks)
  try {
    return crypto.timingSafeEqual(
      Buffer.from(signature, 'hex'),
      Buffer.from(expected, 'hex'),
    );
  } catch {
    return false;
  }
}

// Express middleware
app.post('/webhooks/bamboohr',
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const sig = req.headers['x-bamboohr-signature'] as string;
    const ts = req.headers['x-bamboohr-timestamp'] as string;

    if (!verifyBambooHRWebhook(req.body, sig, ts, process.env.BAMBOOHR_WEBHOOK_SECRET!)) {
      return res.status(401).json({ error: 'Invalid webhook signature' });
    }

    // Safe to process
    const event = JSON.parse(req.body.toString());
    handleWebhookEvent(event);
    res.status(200).json({ received: true });
  },
);

Step 3: PII Data Handling

BambooHR employee data includes PII and sensitive fields. Handle accordingly.

// Define sensitivity levels for BambooHR fields
const FIELD_SENSITIVITY: Record<string, 'public' | 'internal' | 'confidential' | 'restricted'> = {
  firstName: 'internal',
  lastName: 'internal',
  displayName: 'internal',
  jobTitle: 'internal',
  department: 'internal',
  workEmail: 'internal',
  homeEmail: 'confidential',
  homePhone: 'confidential',
  mobilePhone: 'confidential',
  address1: 'confidential',
  dateOfBirth: 'confidential',
  ssn: 'restricted',
  payRate: 'restricted',
  payType: 'restricted',
  maritalStatus: 'confidential',
  gender: 'confidential',
  ethnicity: 'restricted',
  eeo: 'restricted',
};

// Only request fields you actually need
function safeFieldRequest(neededFields: string[]): string[] {
  const restricted = neededFields.filter(f => FIELD_SENSITIVITY[f] === 'restricted');
  if (restricted.length > 0) {
    console.warn(`Requesting restricted fields: ${restricted.join(', ')}. Ensure compliance.`);
  }
  return neededFields;
}

// Redact PII from logs
function redactForLogging(employee: Record<string, string>): Record<string, string> {
  const redacted = { ...employee };
  const sensitiveFields = ['ssn', 'dateOfBirth', 'homeEmail', 'homePhone',
    'mobilePhone', 'address1', 'payRate', 'gender', 'ethnicity'];
  for (const field of sensitiveFields) {
    if (redacted[field]) redacted[field] = '***REDACTED***';
  }
  return redacted;
}

Step 4: Access Control Audit

// Audit which API key permissions are actually needed
interface AccessAudit {
  endpoint: string;
  method: string;
  requiredPermission: string;
  used: boolean;
}

const ACCESS_MAP: AccessAudit[] = [
  { endpoint: '/employees/directory', method: 'GET', requiredPermission: 'employee:read', used: true },
  { endpoint: '/employees/{id}/', method: 'GET', requiredPermission: 'employee:read', used: true },
  { endpoint: '/employees/{id}/', method: 'POST', requiredPermission: 'employee:write', used: false },
  { endpoint: '/employees/{id}/tables/compensation', method: 'GET', requiredPermission: 'admin', used: false },
  { endpoint: '/time_off/requests/', method: 'GET', requiredPermission: 'timeoff:read', used: true },
  { endpoint: '/webhooks/', method: 'POST', requiredPermission: 'webhooks:manage', used: false },
];

// Principle of least privilege: only enable permissions for endpoints you use
const neededPermissions = new Set(
  ACCESS_MAP.filter(a => a.used).map(a => a.requiredPermission),
);
console.log('Required permissions:', [...neededPermissions].join(', '));

Step 5: Security Checklist

- [ ] API keys stored in environment variables or secret manager (never in code)
- [ ] `.env` files in `.gitignore`
- [ ] Separate API keys for dev / staging / prod
- [ ] API key user has minimum required access level
- [ ] Webhook signatures verified with HMAC-SHA256
- [ ] Webhook timestamp checked (reject > 5 min old)
- [ ] PII fields redacted from logs and error messages
- [ ] Only requesting needed fields (not SELECT *)
- [ ] Restricted fields (SSN, salary) only accessed when required
- [ ] Data at rest encrypted if storing BambooHR data locally
- [ ] API key rotation scheduled (quarterly minimum)
- [ ] git-secrets or truffleHog scanning enabled

Output

• Secure API key storage and rotation procedure
• Webhook HMAC verification middleware
• PII classification and redaction utilities
• Access control audit framework
• Security compliance checklist

Error Handling

Security Issue	Detection	Mitigation
Exposed API key in git	git-secrets, GitHub secret scanning	Rotate immediately; add pre-commit hook
Webhook replay attack	Timestamp > 5 min old	Reject and alert
PII in logs	Log audit	Add redaction middleware
Over-permissioned key	Access audit	Create new key with minimal permissions

Resources

• BambooHR Webhooks Security
• BambooHR Authentication

Next Steps

For production deployment, see bamboohr-prod-checklist.