Planned Changes to the API

2025.11.07 – Deprecating HTTP Authentication Negotiation (removing WWW-Authenticate: Basic realm on 401)

We are deprecating support for HTTP authentication negotiation in our public APIs. Today, some clients (e.g., PowerShell scripts) send an unauthenticated request, receive a 401 with a Basic realm challenge, and then retry with credentials. To provide a consistent and reliable authentication experience across all integrations, we’re removing the Basic realm challenge—which can cause confusing browser credential prompts when sessions expire—by eliminating the WWW-Authenticate: Basic realm="..." header from 401 responses.

What’s changing

• The WWW-Authenticate: Basic realm="..." header will no longer be returned on 401 responses.
• Clients must send credentials with the initial request (or use OAuth 2.0 tokens).
• Integrations that already send the Authorization header up front are not affected.

Action required

• If your script or integration relies on a 401 challenge/negotiation flow, update it to include the Authorization header in the initial request (Basic with your BambooHR API key), or use OAuth 2.0 access tokens.
  BambooHR’s API uses Basic Auth with the API key as the username and any string as the password.

Timeline

• Announcement: November 7, 2025
• Removal enforced after: February 28, 2026
• After enforcement: requests that depended on negotiation may receive 401 errors without an automatic retry.

PowerShell example (send credentials with the first request)

Replace your-subdomain, YOUR_API_KEY, and the sample endpoint with your own. In Basic Auth for BambooHR, use the API key as the username and any string for the password.

# 1) Provide your BambooHR API key as the username; use any string as the password
$apiKey   = "YOUR_API_KEY"
$password = "x" | ConvertTo-SecureString -AsPlainText -Force
$cred     = New-Object System.Management.Automation.PSCredential($apiKey, $password)

# 2) Build the Basic Authorization header manually (send on the FIRST request)
$authString  = "$($cred.UserName):$($cred.GetNetworkCredential().Password)"
$encodedAuth = [Convert]::ToBase64String([System.Text.Encoding]::UTF8.GetBytes($authString))
$headers     = @{ "Authorization" = "Basic $encodedAuth" }

# 3) Call the API (example endpoint shown)
$uri = "https://your-subdomain.bamboohr.com/api/v1/employees/directory"

try {
  # Use Invoke-RestMethod or Invoke-WebRequest; do NOT rely on negotiation or default creds
  $response = Invoke-RestMethod -Uri $uri -Method Get -Headers $headers
  Write-Host "Request successful."
  $response | ConvertTo-Json -Depth 6
}
catch {
  Write-Host "Request failed. Error: $($_.Exception.Message)"
}

More Information

• For more information about authentication, see Getting Started With The API.