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. Nothing changes in your HubSpot account unless you approve it.
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: your first audit for each portal is free; see Pricing for the paid plans. 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 (including totals of calls, meetings, notes and tasks; activity text is not stored) and field-completeness checks (counts only; no contact records are copied) |
| Companies | crm.objects.companies.read | Record counts, field-completeness checks, and a count of companies with num_associated_contacts above zero when that property is on the schema |
| Deals | crm.objects.deals.read | Record counts, open-deal field completeness, deal pipelines and stages, and pipeline definition-change counts (action and timestamp only) |
| 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), including lifecycle stage options and their order, and property validation rule types |
| Companies | crm.schemas.companies.read | Property definitions, including lifecycle stage options and their order, and property validation rule types |
| Deals | crm.schemas.deals.read | Property definitions and property validation rule types |
| 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, last-updated dates, and deal-list filter property names |
| Account security | account-info.security.read | Login history, security activity and audit-log summaries (last 90 days); private-app API usage and daily headroom (currentUsage, usageLimit, resetsAt) |
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, dates, and configuration enums (lifecycle count, notify flags, consent type). Field values, consent copy, and notifyRecipients ids are not stored. 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, plus deal-workflow property names (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 domain names and flags (resolving, HTTPS, primary email). A declined scope skips the check |
| Goals | crm.objects.goals.read | How many goal targets exist (the id only; owner and creator ids are not requested) |
| Leads | crm.objects.leads.read | Whether the leads object is turned on, then the lead total (one search, id only) |
| Meetings | scheduler.meetings.meeting-link.read | How many meeting links exist (the total only; link URLs and organizer ids are not stored) |
| Reporting | reporting.full.read | How many custom reports and dashboards exist, not counting HubSpot's default reports, and how many reports are on no dashboard, were not viewed in 180 days, or were never viewed (counts only; report names are not kept) |
| Knowledge base | cms.knowledge_base.articles.read | How many knowledge base articles exist. Article bodies are not requested |
| Feedback | crm.objects.feedback_submissions.read | How many feedback survey responses exist (the total only; answers are not read) |
| Orders | crm.objects.orders.read | How many orders exist (the total only; amounts and line items are not read). Skipped when the permission is not granted or orders are turned off |
| Invoices | crm.objects.invoices.read | How many invoices exist (the total only; amounts and line items are not read). Skipped when the permission is not granted or invoices are turned off |
| Subscriptions | crm.objects.subscriptions.read | How many commerce subscriptions exist (the total only; amounts and line items are not read). Skipped when the permission is not granted or subscriptions are turned off |
| Commerce payments | crm.objects.commercepayments.read | How many commerce payments exist (the total only; amounts, status, and payer details are not read). HubSpot lists this permission for Starter accounts. Skipped when it is not granted or payments are turned off |
| Sequences | automation.sequences.read | How many sequences exist, read user by user because HubSpot lists sequences per user (counts only; sequence names, steps and enrolled contacts are not kept) |
Write permissions are not on this install link. They are requested only from a Fix reauthorize on this same app, and nothing changes in your portal unless you approve it.
| HubSpot data | Scope | What a fix may change, only after you approve it |
|---|---|---|
| Contacts | crm.objects.contacts.write | Contact property updates for an approved fix. Not requested on the public install link. Unused until you approve a fix. |
| Contacts | crm.schemas.contacts.write | Contact property definition updates for an approved fix. Not requested on the public install link. Unused until you approve a fix. |
| Companies | crm.schemas.companies.write | Company property definition updates for an approved fix. Not requested on the public install link. Unused until you approve a fix. |
| Deals | crm.schemas.deals.write | Deal property definition updates for an approved fix. Not requested on the public install link. Unused until you approve a fix. |
| Deals | crm.objects.deals.write | Deal property updates for an approved fix. Not requested on the public install link. Unused until you approve a fix. |
| Tickets | crm.objects.tickets.write | Ticket property updates for an approved fix. Not requested on the public install link. Unused until you approve a fix. |
| Companies | crm.objects.companies.write | Company property updates for an approved fix. Not requested on the public install link. Unused until you approve a fix. |
| Users | settings.users.teams.write | Team changes for an approved fix. Not requested on the public install link. Team writes stay banned for customer portals. |
Why these permissions
- The audit path only reads. Before an audit request goes to HubSpot, it is checked against an allowlist of read requests in the app's code (how this is enforced is described in the Security section of our Privacy Policy). Anything that would create, change or delete data is blocked on that path before it leaves our server, and the audit stops. Fixes use a different path, and that path stays off until you approve a fix.
- No Sensitive Data permissions. Portal Audit never requests HubSpot Sensitive Data or Highly Sensitive Data permissions, and never reads or checks that data. That includes any permission whose name contains
.sensitive.or.highly_sensitive., and the older ticket permissionstickets.sensitiveandtickets.highly_sensitive. - 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.
Configure the app and run your first audit
- After you install, you land on a confirmation page. Confirm your company's industry, size and website. This tailors the best-practice checks to your business.
- On the same page, two boxes are unticked until you tick them. The first chooses whether Portal Audit may read your public website and public sources about your company. If you leave it unticked, or choose "Continue without tailoring", no website or outside research happens and the report says it is not tailored. The second chooses org-chart enrichment (public job titles). It stays off unless you tick it, even if website research is on. Your first audit starts after this step.
- The audit runs. 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 first report within 1 day, after it is reviewed, as a PDF (and, on request, the underlying data as JSON or Markdown).
- Optional: a scheduled audit on a day and time you choose (monthly on Watch, weekly on Watch Weekly and Fix), with changes and fix-plan progress. The paid plans also accept a credit and seat usage file that you download from HubSpot's Credits tab. If you change plans, upgrades on the same billing period apply right away; downgrades take effect at the next renewal, with no refund for the current period, and your weekly or monthly schedule changes then (see Pricing).
See your audit in HubSpot
Open Portal Audit from the Marketplace icon in the HubSpot account where it is installed (Your recently visited apps). The page leads with what is working, then the quick wins, then the score, then the findings. A first audit that is still in review shows that status only.
Nothing changes in your portal unless you approve it. Opening this page does not ask for any new permissions.
Use the app: read the report
- Object inventory: a table near the top of the report with one row per CRM object, whether it is standard or custom, and the record count. A row says not assessed when a permission is missing or the count could not be read. The table stores counts only.
- 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 scheduled 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.
Already installed, and new optional permissions were added
HubSpot does not add new optional permissions to an existing install on its own. To grant them:
- Sign in as a Super Admin (or a user with App Marketplace access) on the account.
- Open
https://audit.thejonmartin.com/oauth/install?portalId=YOUR_PORTAL_ID(production:https://audit.thejonmartin.com/oauth/install?portalId=YOUR_PORTAL_ID). - Leave the new optional permissions checked and click Connect.
That is a reauthorize. It does not reset your audit schedule and it does not start another first audit. The exact steps for the portal this app is operated from are in the repository file docs/SCOPES.md.
Get help
See Support, or email jon@thejonmartin.com.