Guide / Pipeline and CRM
Replace a HubSpot private app: service keys, and where they stop
A HubSpot service key replaces a private app for an agent that makes REST calls in one account. Webhooks, UI extensions or many accounts need a project app.
An enrichment agent that writes firmographics back to HubSpot used to get its access from a private app. That option is now gone. HubSpot stopped letting anyone create new legacy private apps on 28 September 2026 for accounts created on or after that day, and on 26 October 2026 for older accounts. Every existing private app keeps working as it was.
HubSpot's replacement is the service key, and it is the right choice for an agent that only makes REST calls in a single account. An agent that listens for record changes, or works across several accounts, needs a project app with a static token or OAuth.
By the end you will have a service key that reads and writes company records, and the header the agent sends it in. To create one, you need to be a super admin in the HubSpot account, or hold the Developer tools access permission.
How to set up a HubSpot service key for company reads and writes
The whole setup happens in the HubSpot account, with no command-line tools. These steps follow HubSpot's service key documentation.
- In HubSpot, open Development, then Keys > Service keys. Click Create service key and name it after the agent.
- Click Add new scope, tick
crm.objects.companies.readandcrm.objects.companies.write, then click Update. HubSpot's scopes reference says the write scope covers creating, deleting and changing companies, so the key can delete records as well as edit them. - Review the scope summary, click Create and confirm.
- Open the key, click Show, then Copy, and store the key wherever the agent keeps its secrets.
- Have the agent send the key as a Bearer token in the Authorization header; it works as soon as it is created.
- Turn on automatic rotation every 3, 6 or 12 months. Or rotate by hand with Rotate and expire later, which keeps the old key valid for seven days while the agent picks up the new one.
- Use View logs on the key's page to see the requests the agent has made.
Example calls
The company write-back itself, reading a batch of companies and then updating them with this key, is walked through in our guide to connecting an AI agent to HubSpot. The calls below show the header those requests carry. HubSpot's own service key example is a contacts read, so the company-only key above would need a contacts scope to send it as written.
curl --request GET \
--header "Authorization: Bearer pat-na1-*********-****-****-****-************" \
--url "https://api.hubapi.com/crm/v3/objects/contacts?limit=10&archived=false"
A project app's static token goes in the same header. An agent you later move from a key to an app keeps the same header and swaps the token.
curl --request GET \
--header "Authorization: Bearer ***-***-*********-****-****-****-************" \
--url "https://api.hubapi.com/crm/objects/2026-03/contacts?limit=10&archived=false"
Before you replace an existing private app, list what it can do. HubSpot's legacy private app docs describe a token-info request whose response gives the account, the app and its scopes.
POST /oauth/v2/private-apps/get/access-token-info
{
"tokenKey": YOUR_ACCESS_TOKEN
}
{
"userId": 123456,
"hubId": 1020304,
"appId": 2011410,
"scopes": ["crm.schemas.companies.write"]
}
An agent that goes over a limit gets a 429 response on every later call, and the body says which limit it hit.
{
"status": "error",
"message": "You have reached your daily limit.",
"errorType": "RATE_LIMIT",
"correlationId": "c033cdaa-2c40-4a64-ae48-b4cec88dad24",
"policyName": "DAILY",
"requestId": "3d3e35b7-0dae-4b9f-a6e3-9c230cbcf8dd"
}
What it costs
HubSpot caps how many calls an app can make per 10 seconds and per day. The number of calls an app can make depends on the account's subscription and on whether it has bought the API limit increase, according to HubSpot's API usage guidelines. Service keys get the same limits as privately distributed project apps, and those match the limits for legacy private apps:
| Subscription | Per 10 seconds, per key or app | Per day, per account |
|---|---|---|
| Free and Starter | 100 | 250,000 |
| Professional | 190 | 625,000 |
| Enterprise | 190 | 1,000,000 |
| With API limit increase (two at most) | 250 | +1,000,000 per increase |
The 10-second limit applies to each app on its own. The daily limit is shared by every privately distributed app in the account.
The Associations and CRM search APIs have stricter limits of their own. HubSpot's guidelines also recommend batch APIs and caching settings the agent fetches repeatedly.
When this is the wrong tool
A service key only makes REST requests. HubSpot's docs say it cannot authenticate webhooks, make calls inside a UI extension, or use any other developer platform feature. For any of those, HubSpot points you to an app with a static token or OAuth.
| Agent's job | Credential | Scopes and limits that decide it | Where to create it |
|---|---|---|---|
| Reads and writes records over REST in one account | Service key | Scopes chosen per key; REST only | Development > Keys > Service keys |
| Receives webhooks or adds a card to record pages, in one account | Project app, static token | Scopes listed in the app's app-hsmeta.json config; static auth installs in a single account |
hs project create with static auth |
| Works across several customer accounts | Project app, OAuth | Needs a hosted OAuth backend; private distribution allows 10 accounts at a time | hs project create with OAuth |
| Works through HubSpot's remote MCP server | MCP connector | OAuth with PKCE (a standard extra check that a token request is genuine); scopes follow the user's grants | Development > MCP Connectors |
Project apps are built with the HubSpot CLI. HubSpot's app guide walks through choosing the authentication type and adding features such as webhooks, record cards and custom workflow actions, then uploading the project. An OAuth app listed on the HubSpot Marketplace gets 110 requests per 10 seconds for each installing account, and the limit increase does not raise that figure.
The remote MCP server connects through an MCP connector and acts as the user who authorizes it, with that user's permissions. HubSpot also caps project apps, service keys and MCP connectors at 100 combined per account.
HubSpot says existing private apps keep working, and it invites owners to migrate them to the projects framework now. Three points decide when.
- Features. Existing legacy apps are still supported but do not get the latest app features.
- Webhooks. Legacy private apps support webhooks, so one that receives them should move to a project app, not a service key.
- Departing staff. Some calls from a private app fail if the user who created it is removed from the account. An app built by someone who is leaving is worth moving first.
The date to watch is in HubSpot's developer changelog: it has announced that support for legacy private apps ends, with a September 2027 enforcement date.
Frequently asked questions
Do existing HubSpot private apps stop working?
No. HubSpot says existing legacy private apps continue to work as they are; only creating new ones was removed. Its changelog has also announced an end of support for legacy private apps, with a September 2027 enforcement date.
Can a HubSpot service key receive webhooks?
No. HubSpot's docs say service keys cannot authenticate webhooks or make calls inside UI extensions, so an agent that needs either should use a project app with a static token or OAuth.
What rate limits apply to a HubSpot service key?
A service key has the same limits as a privately distributed app: 100 to 190 requests per 10 seconds depending on the subscription, or 250 with the API limit increase. The daily limit, 250,000 to 1,000,000 requests depending on the subscription, is set per account and shared across its privately distributed apps.
Does HubSpot's remote MCP server work with a service key?
No, not as HubSpot documents it. The remote MCP server connects through an MCP connector, HubSpot requires OAuth with PKCE to sign in to it, and the server acts as the user who authorizes it. A service key is for an agent's direct REST calls.
Where do I create a HubSpot service key?
HubSpot's service key docs give the path as Development > Keys > Service keys. The sunset announcement gives it as Settings > Integrations > Service Keys.
Read this article as Markdown Open in ChatGPT Open in Claude


