bamboohr-security-basics

name	bamboohr-security-basics
description	Apply BambooHR security best practices for API keys, webhook verification, and PII data handling compliance. Use when securing API keys, implementing webhook signature validation, or handling sensitive employee data from BambooHR. Trigger with phrases like "bamboohr security", "bamboohr secrets", "secure bamboohr", "bamboohr PII", "bamboohr data protection".
allowed-tools	Read, Write, Grep
version	1.0.0
license	MIT
author	Jeremy Longshore <[e-mail]>
tags	["saas","hr","bamboohr","security"]
compatible-with	claude-code

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  ;

 ():  {
  
   age = .() - (timestamp, ) * ;
   (age >  || age < -) {
    .();
     ;
  }

  
   payload = ;
   expected = crypto
    .(, secret)
    .(payload)
    .();

  
   {
     crypto.(
      .(signature, ),
      .(expected, ),
    );
  }  {
     ;
  }
}


app.(,
  express.({ :  }),
   {
     sig = req.[]  ;
     ts = req.[]  ;

     (!(req., sig, ts, process..!)) {
       res.().({ :  });
    }

    
     event = .(req..());
    (event);
    res.().({ :  });
  },
);