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.

When an API request is made without credentials, BambooHR returns a 401 with a WWW-Authenticate: Basic realm="..." header. Some HTTP clients treat that header as a signal to retry with credentials, a pattern known as HTTP authentication negotiation. While this is part of the HTTP spec, it doubles the round trips for every API call, adding latency and consuming rate limit budget on requests that will always fail.

We strongly recommend configuring your integration to include credentials on every API request from the start rather than relying on this challenge-response cycle. This eliminates the extra round trip, improves reliability by succeeding on the first attempt, and preserves your rate limit budget for productive calls. Most HTTP client libraries support sending credentials preemptively. Consult your library's documentation for how to send the Authorization header with every request.

Note that the WWW-Authenticate: Basic realm header will not be included in future API versions. For improved security and granular access control, we also recommend migrating to OAuth 2.0. See Getting Started With The API for details.