How to migrate from HubSpot API key to private app token authentication in PHP

[scarlettturner]

Switching HubSpot authentication method

I need help updating my PHP application to use HubSpot’s private app access tokens instead of the old API key method. The current implementation builds request URLs by appending the API key as a parameter.

Here’s my existing URL builder function:

/**
 * Builds API request URL with authentication
 *
 * @param string $api_endpoint - The endpoint path to call
 * @param array $query_params - Additional parameters for the request
 *
 * @return string Complete URL for API call
 */
protected function build_api_url($api_endpoint, $query_params = [])
{
    $query_string = $this->convert_params_to_string($query_params);
    
    return $this->get_base_url() . $this->SEPARATOR . $this->get_api_path() . $this->SEPARATOR . 
           $this->get_version() . $this->SEPARATOR . $api_endpoint . 
           $this->API_KEY_PARAM . $this->hubspot_key . $query_string;
}

What changes do I need to make to switch from API key authentication to private app tokens? Should I use headers instead of URL parameters now?

Any guidance would be appreciated!

[sofiag]

Just did this migration a few months back. You’re right - headers replace URL parameters for auth. Strip out that API_KEY_PARAM concatenation from your build_api_url function entirely. Keep the URL clean. For the HTTP request, add the Authorization header instead. With cURL, throw in curl_setopt($ch, CURLOPT_HTTPHEADER, ['Authorization: Bearer ' . $your_private_app_token]); before you execute. Grab the token from your private app settings in HubSpot and update any stored config to use the new format. Test everything thoroughly - permissions work differently between API keys and private apps.

[Grace_31Dance]

I did this migration last year. The main difference is private app tokens use Bearer auth in headers instead of URL parameters. You’ll need to add an Authorization header with Bearer YOUR_PRIVATE_APP_TOKEN instead of sticking the key in the URL. Strip out the API key parameter from your URL building entirely. Update your cURL or HTTP client to send the token in headers. One heads up - private app tokens have more granular permissions, so double-check your private app has all the scopes you need. The endpoint URLs stay the same, just the auth method changes.