Planned Changes to the API

2026.02.18 – Best Practice: Always Send Credentials With API Requests

In November 2025, we announced plans to remove the WWW-Authenticate: Basic realm="..." header from all API 401 responses. After further evaluation, we've taken a more targeted approach to avoid disrupting existing integrations.

Background

When an API request is made without credentials, BambooHR returns a 401 response with a WWW-Authenticate: Basic realm="..." header. Some HTTP clients use this as a signal to retry the request with credentials — a pattern known as HTTP authentication negotiation.

While this pattern is part of the HTTP specification, it doubles the number of HTTP round trips for every API call, adding latency and consuming rate limit budget on requests that will always fail.

Recommended action

We strongly recommend configuring your integration to include credentials on every API request from the start rather than relying on the challenge-response cycle. This is an industry best practice and provides meaningful benefits:

• Faster responses — Eliminates the extra round trip of receiving a 401 and retrying.
• Improved reliability — Requests succeed on the first attempt.
• Reduced rate limit usage — Failed unauthenticated requests count toward rate limits. Authenticating upfront preserves your request budget for productive calls.
• Future compatibility — The WWW-Authenticate: Basic realm header will not be included in future API versions.

Most HTTP client libraries support sending credentials preemptively. Consult the documentation for your specific language or library for how to disable HTTP authentication negotiation and send the Authorization header with every request.

Looking ahead

For improved security and granular access control, we recommend migrating to OAuth 2.0. See Getting Started With The API for details.

2025.11.26 – Upcoming Improvement to Webhook Error Details

We’re enhancing webhook error information to make troubleshooting easier. Soon, webhook error logs will include more detailed and actionable fields, and a new API endpoint will allow developers to retrieve webhook errors programmatically. We expect these improvements to be available in early 2026.