Skip to main content
If you need to set up a simple third-party integration with HubSpot or try out specific HubSpot API endpoints, you can use service keys to query HubSpot’s REST APIs directly without having to use the CLI or other platform developer tools first. Service keys are still configured with object-specific scopes (e.g., crm.objects.contacts.read) so you can still limit access for each key, and keys can be managed or rotated to keep your account data secure.
This functionality is currently in public beta. By participating in this beta, you agree to HubSpot’s Developer Terms and Developer Beta Terms. Note that the functionality is still under active development and is subject to change based on testing and feedback.

​
Before you get started

The following users in your account have access to create and manage service keys:
You cannot use service keys to authenticate webhooks, make calls within a UI extension, or leverage other developer platform functionality other than making REST API requests. If you want to leverage these features, you should create an app and use its static access token or OAuth access token to make API requests instead.

​
Limits

Service keys are subject to the same limits as privately distributed apps built on version 2025.2 and 2026.03 of the developer platform.

​
Create a service key

To create a new service key:
  • In your HubSpot account, navigate to Development.
  • In the left sidebar menu, navigate to Keys > Service keys.
  • In the top right, click Create service key.
Screenshot demonstrating how to create your first service key in the development overview in HubSpot
  • Enter a name for the service key.
  • Click Add new scope.
  • In the right panel, select the checkbox for each scope you want your key to be able to access.
    • You can also search for a specific scope using the Find a scope search bar. You can review a full list of available scopes in this reference article.
    • Click Update when you’re done adding scopes. If you later decide that you require additional scopes, you can also configure them after your key is created.
  • Review the scopes you’ve selected. If you decide your key does not require a specific scope, you can click Delete next to that scope to remove it. You can also click Summary of selected scopes to view a breakdown of your key’s scopes and the associated access granted for each one.
Screenshot showing creating a new service key with contacts read and write scopes
  • When you’re ready, click Create in the top right, then confirm your choice in the dialog box.

​
Make API requests with your service key

Once created, your service key can be used immediately to make requests for data in your account:
  • In your HubSpot account, navigate to Development.
  • In the left sidebar menu, navigate to Keys > Service keys.
  • Click the name of your service key.
  • By default, your service key will be partially hidden for security purposes. Under the key, click Show to toggle its visibility, then click Copy to copy the key to your clipboard.
Screenshot showing service key and how to copy it for use in an API request
  • You can then include your service key as a Bearer token in your preferred API client or programming language. The code block below demonstrates how to include the key in a cURL request in the CLI to retrieve contacts.
curl --request GET \
--header "Authorization: Bearer pat-na1-*********-****-****-****-************" \
--url "https://api.hubapi.com/crm/v3/objects/contacts?limit=10&archived=false"

​
Manage service keys

The details page for your service key provides a centralized space for managing your key.
  • In your HubSpot account, navigate to Development.
  • In the left sidebar menu, navigate to Keys > Service keys.
  • Click the name of your service key, then review and manage your key.
Screenshot of service key details page in development overview in a HubSpot account
  • To change the name or the scopes for your key, click Edit in the top right.
  • To monitor or review recent requests, click View logs in the top right.
If your key is lost or otherwise compromised, you can rotate it. A new service key will be created and the original one will expire.
  • Next to your service key, click Rotate:
    • If your key is compromised and you want to immediately revoke access, click Rotate and expire now.
    • If there’s no imminent threat to your key, it’s still recommended that you rotate it every six months. If you’re ready to initiate a regular rotation of your key, click Rotate and expire later, which will trigger an expiration of the key in 7 days.
      • If your key is ready to transition earlier, you can click Expire now.
      • If you decide you need more time, you can click Cancel rotation, which will cancel the expiration of the original key and revoke the new service key.
To delete the service key:
  • At the bottom of the page, click Delete.
  • In the dialog box, type the name of your key to confirm its deletion, then click Delete.
Last modified on March 30, 2026