Portal Audit setup guide
This guide covers installing Portal Audit in your HubSpot account, running your first audit, reading the report, and disconnecting the app. Portal Audit is read-only: it never changes anything in your HubSpot account.
Before you start
- Who can install: a HubSpot Super Admin, or a user with App Marketplace access who also has permission for each data area the app reads (see HubSpot: connect apps to HubSpot).
- HubSpot plans: any HubSpot account can install. Some sections (workflows, custom objects, connected domains) only run if your plan includes those tools; otherwise the report marks them "not assessed".
- Cost: see the pricing agreed with Portal Audit. Installing the app does not change your HubSpot subscription.
Install the app
- Click Install on the Portal Audit page (https://audit.thejonmartin.com) or in the HubSpot App Marketplace.
- Sign in to HubSpot if asked, then choose the account to connect.
- HubSpot shows the permissions Portal Audit asks for; the tables below explain each one. You can uncheck any optional permission; the related report sections will then show "not assessed" (see Why these permissions).
- Click Connect app. You land on a confirmation page that shows your portal ID and how many permissions were granted.
Permissions the app asks for
Required:
| HubSpot data | Scope | What the audit reads |
|---|---|---|
| Account | oauth | Account details: portal ID, time zone, currency, data hosting location |
| Contacts | crm.objects.contacts.read | Record counts and field-completeness checks (counts only; no contact records are copied) |
| Companies | crm.objects.companies.read | Record counts and field-completeness checks |
| Deals | crm.objects.deals.read | Record counts, field completeness, deal pipelines and stages |
| Tickets | crm.objects.tickets.read | Record counts, field completeness, ticket pipelines and stages |
| Contacts | crm.schemas.contacts.read | Property definitions (names, types, groups, usage flags) |
| Companies | crm.schemas.companies.read | Property definitions |
| Deals | crm.schemas.deals.read | Property definitions |
| Tickets | crm.schemas.tickets.read | Property definitions |
| Line items | crm.objects.line_items.read | Record counts |
| Line items | crm.schemas.line_items.read | Property definitions |
| Quotes | crm.objects.quotes.read | Record counts |
| Quotes | crm.schemas.quotes.read | Property definitions |
| Users | crm.objects.owners.read | Record owners (name, email, active/archived) to find unassigned or departed owners |
| Users | settings.users.read | Users and roles (name, email, role, super admin flag) for the access review |
| Users | settings.users.teams.read | Teams and team membership |
| Segments (lists) | crm.lists.read | Segment names, types, sizes and last-updated dates |
| Account security | account-info.security.read | Login history, security activity and audit-log summaries (last 90 days); private-app API usage |
Optional (you can uncheck these; HubSpot also leaves them out if your plan lacks the tool):
| HubSpot data | Scope | What the audit reads |
|---|---|---|
| Forms | forms | Form names, types and settings (submissions are not read) |
| Marketing email | marketing-email | Marketing email names, states and settings (nothing is sent) |
| Workflows | automation | Workflow names, status, object type, enrollment settings and actions (no workflow is changed) |
| Marketing email | content | Marketing email inventory when the marketing-email scope is not enough (some portals require content) |
| Custom objects | crm.objects.custom.read | Custom object record counts and field completeness |
| Custom objects | crm.schemas.custom.read | Custom object schemas and property definitions |
| Website | cms.domains.read | Connected domains, to find the company website for the business profile |
Why these permissions
- Portal Audit only reads. Before any request goes to HubSpot, it is checked against a read-only allowlist in the app's code (
backend/src/hubspot/allowlist.ts). Anything that would create, change or delete data is blocked before it leaves our server, and the audit stops. - Four permissions have no read-only version in HubSpot. These are forms, marketing-email, automation (workflows) and content. HubSpot's install screen describes them as read and write, because that is the only version HubSpot offers. Portal Audit uses them only to read your forms, marketing emails and workflows.
- All four are optional. You can uncheck them on HubSpot's install screen (HubSpot: optional scopes). If you do, the app skips those checks and the report marks them not assessed. Everything else still runs.
Run your first audit
- After you install, we confirm your company profile with you: industry, company size and website. This tailors the best-practice checks to your business.
- We run the audit. A typical portal takes a few minutes; large portals can take longer because the app stays well under HubSpot's API rate limits.
- You receive the report as a PDF (and, on request, the underlying data as JSON or Markdown).
- Optional: a monthly audit on a day and time you choose, with month-over-month changes and fix-plan progress.
Read the report
- Score and grade: an overall score out of 100, plus a score per area.
- Findings: each finding has a severity, the evidence (counts and names of the settings involved) and the recommended fix.
- Fix plan: findings grouped into ordered steps, with effort estimates. In monthly audits, steps you have completed are marked done.
- Not assessed: sections the app could not check because a permission was not granted or the tool is not in your plan.
Disconnect and uninstall
You can disconnect at any time, in either of two ways:
- In HubSpot: go to Settings → Integrations → Connected apps, find Portal Audit, then Actions → Uninstall (HubSpot instructions).
- Ask us: email jon@thejonmartin.com. We uninstall the app through HubSpot's API; your account admins receive an email from HubSpot confirming it.
What happens to your data:
- Our access to your HubSpot account ends right away, and the stored access credentials are deleted.
- Scheduled audits stop.
- Your reports, company profile and audit history are deleted 30 days after you disconnect, or sooner if you ask.
- Nothing in your HubSpot account changes, because the app never wrote anything there.
Get help
See Support, or email jon@thejonmartin.com.