BambooHR Security Basics Skill

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

Next Steps

For production deployment, see bamboohr-prod-checklist.

Agent Skills: BambooHR Security Basics

Install this agent skill to your local

Skill Files