HubSpot Private App Setup

What You’re Setting Up

A HubSpot private app gives us a secure access token to read and write data in your HubSpot account. It’s the standard way to connect external systems to HubSpot, and it gives you full control over what we can and can’t access.

This takes about 10 minutes.

Prerequisites

• You need Super Admin access in HubSpot. If you’re not sure, go to Settings and check your role under Users & Teams.
• You need a paid HubSpot plan. Free accounts have limited API access.

Step-by-Step Setup

1. Open Private Apps Settings

1. Log into your HubSpot account
2. Click the Settings gear icon in the top navigation bar
3. In the left sidebar, navigate to Integrations, then Private Apps
4. Click the button to create a new private app

2. Configure Basic Info

1. Give the app a name. We recommend something like “AcuCoders Integration” so it’s clear what this is for.
2. Optionally add a description. Something like “Integration managed by AcuCoders” is fine.
3. Add a contact email — your email or your IT contact’s email

3. Set Scopes

Click the Scopes tab. This is where you control what the app can access. For most integrations, we need the following scopes enabled:

CRM:

• crm.objects.contacts.read and crm.objects.contacts.write
• crm.objects.deals.read and crm.objects.deals.write
• crm.objects.companies.read and crm.objects.companies.write

Other common scopes (depending on your integration):

• timeline — for creating custom timeline events on records
• crm.schemas.contacts.read — for reading custom properties
• automation — if workflows are involved

We’ll tell you exactly which scopes to enable. If you’re unsure, enable read and write access for contacts, deals, and companies to start, and we’ll adjust from there.

4. Create and Copy Your Token

1. Click Create app in the top right
2. HubSpot will show you a confirmation dialog — review the scopes and confirm
3. Your access token will appear. Click to copy it.

This token is shown once. You can always reveal it again later in the private app settings, but copy it now to save time.

5. Send Us the Token

Do not email the token in plain text. We’ll provide you with a secure link to submit credentials. If you don’t have that link yet, let us know and we’ll send one.

Verifying the Setup

After you create the app, you’ll see it listed under Settings, Integrations, Private Apps. You can:

• View the token at any time by clicking into the app
• See API call logs to monitor usage
• Edit scopes if we need additional access later
• Rotate the token if it’s ever compromised

Common Issues

Wrong Account

If you manage multiple HubSpot accounts (sandbox, client portals, etc.), make sure you’re logged into the correct account before creating the private app. Check the account name in the top right corner of HubSpot.

Insufficient Permissions

If you don’t see Private Apps under Integrations, your user account likely doesn’t have Super Admin access. Ask your HubSpot admin to either create the app for you or upgrade your permissions.

Token Not Working

If we report the token isn’t working, check that:

• The private app is still active (not paused or deleted)
• The scopes match what we requested
• You copied the full token without extra spaces

Scope Changes

If we need additional access later, you don’t need to create a new app. Edit the existing one, add the new scopes, and the same token will pick up the new permissions.

Next Steps

• If you want to understand the different credential types in HubSpot, read HubSpot API Credentials
• Ready to start your project? Complete the onboarding checklist
• Learn more about our HubSpot Implementation Services