BambooHR is often the system of record for employee identity, compensation and bank details, so its access levels, sign-in settings and API keys decide who can read or change some of the most sensitive data in the business. BambooHR gives customers access levels that scope which employees and fields each user can see, 2-Step Login with an authenticator app, SAML single sign-on, per-user API keys, OAuth for applications, and signed webhooks for change notification. This guide explains how each works according to BambooHR's documentation, how they interact, and how to run them securely. It is for HR systems administrators, identity engineers and security teams in small and mid-sized organisations that use BambooHR.
This is an independent guide from NHI Mgmt Group, based on BambooHR's public documentation as of November 2026. It is not sponsored or reviewed by BambooHR. Product features change, so confirm settings against BambooHR's current documentation.
Key takeaways
- API keys act as the user who created them. BambooHR authorises API requests as if that user were in the web interface, so a key created by a Full Admin can read and change everything that admin can.
- Pick one place for MFA. Use BambooHR 2-Step Login with an authenticator app, or SAML SSO with MFA at your identity provider; confirm in BambooHR's current help how the two interact before you switch.
- Custom access levels beat Full Admin. Give integration users and most HR staff a custom access level scoped to the employees and fields they need.
- Verify webhook signatures. BambooHR signs each webhook with a SHA-256 HMAC in
X-BambooHR-Signature; recompute and compare in constant time before trusting a payload. - Watch bank detail changes. Use webhooks or reports on pay and deposit fields, and confirm changes out of band before payroll runs.
How identity and access work in BambooHR
Each BambooHR user has a login and an access level. The access level decides which employees are in scope and which fields in each section (Personal, Job, Benefits and so on) the user can view or edit, plus whether employees see information about themselves.
| Element | How it works | Customer decision |
|---|---|---|
| Access levels | Managed under Settings > Access Levels; levels include employee self-service, manager, custom and Full Admin, with an Account Owner role above Full Admin | Default to self-service; build custom levels for HR roles and integrations |
| Employee scope | Each level selects which employees it covers, for example all employees or a subset | Scope HR staff to the populations they support |
| Field permissions | View or edit per field, per section | Keep compensation and banking fields to payroll roles |
| Sign-in | Username and password with optional 2-Step Login, or SAML SSO | Federate where you have an IdP |
| User creation | Settings > Security > Users, or via account-creation tools and the API | Tie creation to your HR-driven joiner process |
2-Step Login
BambooHR's 2-Step Login asks for a code from an authenticator app in addition to username and password, and BambooHR states it is available to all customers regardless of package. Administrators manage it from the account settings; check BambooHR's help article for the current menu path and enforcement options. Plan a rollout date, communicate it, and check enrolment before enforcing it.
SAML single sign-on
BambooHR offers a SAML plugin app that customers install in their BambooHR account, so users sign in through their identity provider instead of a BambooHR password. BambooHR publishes service provider metadata at https://{company}.bamboohr.com/saml/sp_metadata.php for the identity provider to consume. Each identity provider user should map to a matching BambooHR user. Move MFA enforcement to the IdP at the same moment; see the SAML Security Guide and the Phishing-Resistant MFA Guide.
Admin roles and privileged access
- Account Owner: the top-level owner of the BambooHR account. Assign it to a named role holder, not a shared mailbox, and document the transfer process for when that person leaves.
- Full Admin: broad access to settings and employee data. Keep the number small and review holders quarterly.
- Payroll and HR custom levels: give compensation, tax and banking edit rights only to the roles that process payroll, and keep approvals with a different person.
- API key creation: the API Keys option appears only when a user's permissions allow it. Restrict it to administrators who own integrations.
- Admin MFA first: whichever MFA route you choose, enforce it on Full Admins and the Account Owner before anyone else. See the SaaS Admin Account Protection guide.
Integrations, API tokens and service accounts
BambooHR offers two API authentication models, both documented on its developer site.
| Model | How it works | Use for | Security points |
|---|---|---|---|
| API key | Created from the user menu > API Keys; a 160-bit hexadecimal value sent as the HTTP Basic username to https://{companyDomain}.bamboohr.com/api/v1/ | Single-customer integrations and scripts | Inherits the creating user's access; repeated use of an unrecognised key temporarily disables API access with HTTP 403 |
| OAuth | App registered in the BambooHR developer portal with client ID and secret; authorisation code flow; access tokens last 3,600 seconds; refresh token only with the offline_access scope | Applications serving many customers | Exact redirect URI match; request only the scopes needed; protect refresh tokens |
- Dedicated integration users: because a key carries its user's permissions, create a dedicated BambooHR user per integration with a custom access level limited to the employees and fields the integration reads. Some vendors ask for Full Admin; challenge that and grant the narrower set their documentation lists.
- Never use a person's key for a production integration: when that person leaves and their account is disabled, the integration breaks, and while they stay it runs with all their rights.
- Store keys in a vault: copy the key once at creation into a secrets manager, never into code or tickets. Replace keys on a schedule and when an integration owner changes.
- Inventory: list every key, its user, its consumer and its owner. See the API Key Management Guide and the Non-Human Identity (NHI) Guide.
Webhooks
BambooHR has two webhook types. Global webhooks are set up by administrators in settings and monitor a predefined field list (custom fields are supported, custom tables are not). Permissioned webhooks are created through the API and can monitor any field the creating user can access. Payloads go only to HTTPS endpoints, are retried up to five times on network errors or 5xx responses, and carry X-BambooHR-Timestamp and X-BambooHR-Signature headers. Verify the HMAC from the raw body, timestamp and your private key with a constant-time comparison, reject stale timestamps, and keep the private key in a vault.
Logging and detection
- Audit trail: BambooHR provides an audit trail of changes in the application; review changes to access levels, user accounts and pay or banking fields, and export what your retention policy needs.
- Change webhooks: a webhook on banking, address and work email fields feeds your SIEM or payroll team with near real-time change events, including changes made through the API.
- IdP logs: with SAML, sign-in risk signals (new device, unusual location, MFA failures) appear in your identity provider.
- API errors: HTTP 403 responses caused by repeated unrecognised keys suggest guessing or a stale integration.
| Event | Why it matters |
|---|---|
| User raised to Full Admin or new access level created | Privilege change (ATT&CK T1098 Account Manipulation) |
| Bank or deposit details changed, especially with a contact detail change in the same session | Classic payroll diversion pattern |
| New API key created | New non-human access |
| 2-Step Login enforcement changed or SAML app removed | Weakens sign-in |
| Sign-in from an unfamiliar location to an admin account | Possible stolen credentials (T1078.004 Cloud Accounts) |
Metrics: percentage of users covered by enforced MFA (target 100%), number of Full Admins, API keys owned by dedicated integration users, keys older than your rotation period, and bank changes verified out of band before payroll (target 100%).
Third-party integrations and connectors
Many BambooHR deployments connect payroll, benefits, applicant tracking, identity governance and SaaS security tools. Each connection is either an API key on a BambooHR user or an OAuth grant, and each one can read employee data at scale. Before connecting a new product, ask the provider which fields and employees it reads, whether it writes back, which access level it needs, and how it stores the key or refresh token. Record the answers in your integration inventory with a business owner. When an integration is retired, delete its key and disable its dedicated user on the same day, then confirm in the next access review that no requests arrive with the old credential. Treat requests for Full Admin from integration providers as a design discussion, not a default: a read-only custom level with the documented field list usually serves directory sync and security monitoring use cases. The same discipline applies to webhooks: remove the endpoint and its private key when the receiving system is decommissioned.
Hardening baseline
- Choose the MFA route: if you have an IdP, install SAML Single Sign-On and enforce MFA there; otherwise require 2-Step Login for all users from a set date.
- Admins: name the Account Owner, cut Full Admins to the minimum, and enforce MFA on them first.
- Access levels: default everyone to self-service; build custom levels for HR, payroll, managers and each integration; restrict banking and compensation edit rights.
- API keys: one dedicated user and key per integration, keys in a vault, OAuth for any multi-customer application.
- Webhooks: monitor sensitive fields, verify signatures, alert payroll and security on changes.
- Payroll process: confirm bank changes through a known channel, notify the employee of any change on a channel other than the one used to make it, and review first payments to new accounts. See the Payroll Diversion Fraud Guide.
- Lifecycle: disable BambooHR access as part of offboarding; see the Employee Offboarding Security Guide.
- Test and roll back: test SAML with a pilot group and keep an administrator path to undo the app install if the IdP connection fails.
Decision guidance
| Decision | Option A | Option B | When to choose which |
|---|---|---|---|
| MFA route | 2-Step Login enforced for all users | SAML SSO with MFA at the IdP | 2-Step Login suits organisations without an IdP and is available on every package; SAML suits organisations that already enforce MFA and conditional access centrally |
| Integration authentication | API key on a dedicated user | OAuth application | API keys suit internal scripts and single-tenant integrations; OAuth suits applications that serve many BambooHR customers and need user consent and short-lived tokens |
| Change notification | Global webhook | Permissioned webhook | Global webhooks are simple to set up in settings for standard fields; permissioned webhooks reach any field the creating user can access, so create them from a dedicated integration user |
| HR staff access | Full Admin | Custom access level | Reserve Full Admin for the few people who configure the account; everyone else gets a custom level |
In a small company the BambooHR administrator is often also the payroll processor and the IT contact, which makes separation of duties hard. Compensate with process: confirm every bank change by phone on a number already on file, keep a second person reviewing the payroll register before release, and keep API keys under a dedicated integration user rather than the administrator's own account. As headcount grows, move the same rules into custom access levels, webhooks and SIEM alerts so they no longer depend on one person remembering them.
Common misconfigurations
- Integration on an admin's personal key: it inherits full rights and dies with the admin's account. Use a dedicated user.
- SAML installed, MFA not moved: once users sign in through the IdP, an IdP policy without MFA leaves sign-in on passwords alone.
- Full Admin for every HR team member: custom levels cover most HR work.
- Webhook receivers that skip signature checks: unsigned or replayed requests could trigger downstream changes. Verify every request.
- Bank changes trusted because they came from self-service: a phished employee login looks like the employee. Verify out of band.
- Keys never inventoried: leftover keys from old integrations stay valid while their user is active.
Framework mapping
| Control area | NIST SP 800-53 Rev 5 | CIS Controls v8.1 | ISO/IEC 27001:2022 Annex A |
|---|---|---|---|
| MFA and SSO | IA-2 | 6.3, 6.5 | A.8.5 Secure authentication |
| Access levels | AC-3, AC-6 | 6.8 Role-based access control | A.5.15 Access control |
| Admin accounts | AC-6 Least Privilege | 5.4 | A.8.2 Privileged access rights |
| API keys and OAuth secrets | IA-5 Authenticator Management | 5.6 | A.5.17 Authentication information |
| Lifecycle | AC-2 Account Management | 5.3, 6.2 | A.5.18 Access rights |
| Change monitoring | AU-2, AU-6 | 8.2 | A.8.15 Logging |
Practitioner checklist
- Decide between enforced 2-Step Login and SAML with IdP MFA, and implement it for all users.
- Name the Account Owner and reduce Full Admins to the minimum.
- Build custom access levels for HR, payroll, managers and integrations.
- Restrict banking and compensation edit rights to payroll roles.
- Create one dedicated user and API key per integration and vault the key.
- Use OAuth with minimal scopes for multi-customer applications.
- Set up signed webhooks on banking and contact fields and verify signatures.
- Verify every bank change out of band before payroll.
- Review admins, access levels and API keys quarterly.
Standards and references
- BambooHR: API getting started (authentication)
- BambooHR: Webhooks
- BambooHR: 2-Step Login
- BambooHR: SAML 2.0 Single Sign-On
- NIST: SP 800-53 Rev 5 Security and Privacy Controls
- CIS: Critical Security Controls v8.1
Related NHI Mgmt Group resources: Payroll Diversion Fraud Guide · API Key Management Guide · SAML Security Guide · Joiner-Mover-Leaver Guide · SaaS Admin Account Protection