API Key → OAuth Migration Guide

The existing API key system is being deprecated and will be retired in the future. All future development will transition to OAuth to better facilitate secure access and limit functionality through scoped permissions.

OAuth provides superior control over API endpoints by utilizing scopes and granular permissions. Previously, most third-party applications required administrative credentials for installation, granting them full access to all users and every API. In contrast, OAuth limits access to specific APIs and permissions, ensuring applications only have the data they need.

Authentication Comparison

Step‑by‑Step Migration Process

1. Create an application
2. Implement OAuth authentication
3. Set the needed scopes
4. Update integration to use the OAuth token instead of API keys
5. Validate responses
6. Disable API key usage

Create an application

If you haven't already done so for your API-key-powered integration, register on the Developer Portal to create an application.

This will give you the details needed for your application:

1. client id
2. client secret
3. redirect URIs
4. scopes

Implement OAuth authentication

If you have an existing, API key powered integration, implementing OAuth can be done alongside your existing authentication.

See code examples below using http, along with links to the official SDK

Supported Grant Type

BambooHR supports the Authorization Code Grant for third‑party applications.

OAuth Roles

• Resource Owner: BambooHR customer user
• Client: Your third‑party application
• Authorization Server: BambooHR OAuth service
• Resource Server: BambooHR API

High‑Level OAuth Flow

1. User is redirected to BambooHR to authorize your application
2. User consents to requested scopes
3. BambooHR redirects back with an authorization code
4. Your server exchanges the code for tokens
5. Access token is used to call the BambooHR API

Step‑by‑Step Authorization Code Flow

1. Redirect User to Authorization Endpoint

GET https://{companyDomain}.bamboohr.com/authorize.php?request=authorize

Query Parameters

Example (Browser Redirect)

https://{companyDomain}.bamboohr.com/authorize.php?request=authorize
response_type=code&
client_id=abc123&
redirect_uri=https://example.com/callback&
scope=employees.read+time_off.read&
state=xyz

2. User Consent

The user authenticates and approves the requested permissions.

3. Authorization Code Returned

https://example.com/callback?code=AUTH_CODE&state=xyz

Validate the state value before continuing.

4. Exchange Authorization Code for Tokens

POST https://{companyDomain}.bamboohr.com/token.php?request=token

Request Body

grant_type=authorization_code
client_id=abc123
client_secret=shhh
code=AUTH_CODE
redirect_uri=https://example.com/callback

Response

{
  "access_token": "eyJhbGci...",
  "refresh_token": "def456",
  "expires_in": 3600,
  "token_type": "Bearer",
  "scope": "employees.read"
}

You should then redirect the client to a success page or similar to show that the process has completed successfully.

Examples

Platform API SDK References

If available, developers should prefer the BambooHR Platform API SDK for:

• OAuth handling
• Token refresh automation
• Typed API clients

See SDK documentation for language‑specific guidance.

PHP Code Examples

There is a specific example on how to implement OAuth 2.0, including handling the authentication redirect and storing tokens.

Checkout the rest of our PHP SDK Github repository for more examples on how to use the API.

Token Management Best Practices

Access Tokens

• Short‑lived
• Include in API requests as:

Authorization: Bearer ACCESS_TOKEN

Refresh Tokens

• Store securely (encrypted at rest)
• Use server‑side only
• Rotate on each refresh if supported

Token Refresh

POST https://{companyDomain}.bamboohr.com/token.php?request=refresh_token

grant_type=refresh_token
refresh_token=REFRESH_TOKEN
client_id=abc123
client_secret=shhh

Set the needed scopes

If you have an existing, API-key-powered integration, you likely already know which endpoints in the BambooHR API your integration needs to access. The BambooHR API documentation indicates which scopes are needed to access those endpoints. You can map your existing API key use cases to the appropriate OAuth scopes

In the Developer portal, update your application to request only the scopes you need.

Example Scopes

Over‑scoping may reduce user trust and approval rates.

Update integration to use the OAuth token instead of API keys

For your integration to call the BambooHR API, it will need to provide a header, Authorization: Bearer <oauth token>.

If you have a current, API key powered integration, you can put this call in wherever you are currently providing the API key in the username/password portion of the request.

Validate responses

The BambooHR API's behavior should be the same with either API Keys or OAuth tokens

Disable API key usage

Once you are confident your integration is functioning as expected with OAuth authentication instead of API keys, it may be prudent to remove API key usage from your integration. This will ensure that you are not affected when API key authentication is officially disabled.

Error Handling & Troubleshooting

Common OAuth Errors

Best Practices

• Log full error responses
• Retry only when safe
• Surface actionable messages to users

Common Migration Pitfalls

Testing & Validation

Recommended Testing Steps

• Validate authorization flow in sandbox
• Confirm scope enforcement
• Test token refresh and expiry
• Revoke access and re‑authorize

Validation Checklist

• ✅ Correct scopes granted
• ✅ API responses match expectations
• ✅ Errors handled gracefully

Support & Resources

• Getting Started with the API
• BambooHR Support

Last Updated: 2025‑12‑30