Permissions & scopes

FlowState asks HubSpot for 12 OAuth scopes (permissions). This page explains why each one is needed, and what FlowState does and does not do with it.

Scopes requested

oauth

Why it is needed: The base scope HubSpot requires for any OAuth app installation. It grants no data access on its own.

crm.objects.deals.read

Why it is needed: FlowState reads your deal records for the analysis, the pipeline pages and the AWS opportunity. Without this scope, no pipeline data can be fetched.

What FlowState does with this access:

• Reads deal properties (name, stage, close date, amount, owner, and all custom properties including the APN properties).
• Reads deal association metadata to find contacts linked to each deal.

What FlowState never does with this access:

• Reads deals from HubSpot portals not linked to your FlowState tenant.
• Keeps pipeline data longer than 1 day, or AI deal summaries longer than 8 days.

crm.objects.deals.write

Why it is needed: FlowState writes the APN sync status and the AWS review results to its own properties on each deal, so your team sees them in HubSpot.

What FlowState does with this access:

• Updates only the properties in the flowstate_apn property group, on deals that have APN sync turned on.
• Creates a deal when AWS sends you a co-sell opportunity that started in AWS, such as an invitation.

What FlowState never does with this access:

• Modifies your own deal properties such as the deal name, stage, close date, amount or owner.
• Deletes deals.

crm.objects.owners.read

Why it is needed: FlowState shows the owner’s name on each deal, in the pipeline pages and in Slack alerts, instead of an ID.

What FlowState does with this access:

• Reads owner records (name, email) for owners assigned to deals in the connected portal.

What FlowState never does with this access:

• Creates, modifies, or unassigns owners.

crm.objects.appointments.read

Why it is needed: The deal analysis reads the meetings associated with a deal, with its notes, emails, calls and tasks, to see how recently the deal was worked on and to summarise it.

What FlowState does with this access:

• Reads appointment/meeting records associated with deals for activity-recency and win/loss analysis.

What FlowState never does with this access:

• Reads appointments not associated with a deal, or modifies/creates appointments.

crm.schemas.deals.read

Why it is needed: Before creating or updating a property, the provisioner checks whether it (or the flowstate_apn property group) already exists, so it never has to guess and can safely no-op.

What FlowState does with this access:

• Reads the deal property schema and the list of existing property groups.

What FlowState never does with this access:

• Reads schemas for object types other than deals.

crm.schemas.deals.write

Why it is needed: FlowState creates the flowstate_apn property group and the APN custom properties when you run the provisioner (Settings → Integrations → HubSpot → Provision properties, or the provision_hubspot_properties MCP tool/action). Without this scope, the provisioner cannot create the schema objects.

What FlowState does with this access:

• Creates or updates (idempotently) one property group (flowstate_apn) and the APN deal properties under that group.

What FlowState never does with this access:

• Modifies or deletes properties not in the flowstate_apn group.
• Changes the schema of existing properties your team has defined.

crm.objects.contacts.read

Why it is needed: An AWS opportunity needs at least one client contact. FlowState reads the contacts associated with a deal to fill in the opportunity’s contacts.

What FlowState does with this access:

• Reads the first name, last name and job title of the contacts associated with APN-enabled deals.

What FlowState never does with this access:

• Stores contact personal data after the sync that used it.
• Reads contacts not associated with a deal.
• Reads marketing contact properties (email opt-in status, lifecycle stage, form submissions, page views).

crm.objects.contacts.write

Why it is needed: When AWS adds members to your opportunity team (account owner, sales rep, partner sales manager, ISV success manager), FlowState mirrors each of them into HubSpot as a contact and associates it with the deal, so the AWS people working the co-sell are visible in HubSpot.

What FlowState does with this access:

• Upserts a contact by email (creates if absent, updates if present) for each AWS opportunity team member, setting email, firstname, lastname, and jobtitle.
• Associates each such contact with the corresponding deal (default contact-to-deal association).

What FlowState never does with this access:

• Creates or edits contacts unrelated to an AWS opportunity team.
• Writes marketing contact properties or sets lifecycle/opt-in state.
• Deletes contacts.

crm.objects.companies.read

Why it is needed: The client’s company name, website and country are not deal properties. FlowState reads them from the company associated with the deal to fill in the AWS opportunity. It also uses the company’s industry to pre-fill the card’s Industry field, when that industry matches one of AWS’s industries.

What FlowState does with this access:

• Reads the company record associated with an APN-enabled deal (name, website, country, industry), read-only.

What FlowState never does with this access:

• Reads companies not associated with an APN-enabled deal.

crm.objects.companies.write

Why it is needed: HubSpot has no deal property for a company’s name or website, so when FlowState creates a deal from AWS (an invitation, or an opportunity that started in AWS), it puts the client’s company on a HubSpot company record and links the deal to it.

What FlowState does with this access:

• Searches for the client’s company by its website domain, then by its exact name.
• Creates the company (name, domain, website) only when no match exists.
• Associates the deal with that company (the default deal-to-company association).

What FlowState never does with this access:

• Edits or deletes an existing company.
• Creates companies for deals that did not come from AWS.

sales-email-read

Why it is needed: The deal analysis reads the emails logged on a deal, with its notes, calls, meetings and tasks, to see how recently the deal was worked on and to summarise it. HubSpot requires this scope to read emails associated with a deal.

What FlowState does with this access:

• Reads only the emails associated with the deals it analyses: the timestamp, the subject, the body and the direction.
• Sends at most the 20 newest activities of a deal to the AI analysis.

What FlowState never does with this access:

• Sends, creates, edits or deletes emails.
• Reads emails that are not associated with a deal.

If your connection does not have this scope yet, the deal analysis fails with “HubSpot has not granted FlowState a permission this analysis needs”. Click Reconnect HubSpot in the banner on Settings → Integrations → HubSpot (see Missing permissions) and approve the new scope in HubSpot.

Missing permissions

When you connect, FlowState stores the scopes that HubSpot granted. The connection status compares them with the scopes FlowState requests now. If a scope is missing:

• Settings → Integrations → HubSpot shows a “HubSpot needs new permissions” banner with the missing scopes and a Reconnect HubSpot button. The button starts the same HubSpot authorization as Connect HubSpot; you do not have to disconnect first.
• Settings → Integrations shows a reconnect required badge on the HubSpot card.
• The status response (GET /v1/tenants/{id}/integrations/hubspot and the get_hubspot_status MCP tool) contains:
  • missing_scopes — the missing scopes, sorted. Empty when all are granted or HubSpot is not connected.
  • reconnect_required — true when missing_scopes is not empty.
  • scopes_unknown — true when the connection has no stored scopes. FlowState then cannot tell if a scope is missing, so missing_scopes is empty and reconnect_required is false. Reconnect HubSpot to store the scopes.

FlowState checks the scopes that were stored at connect time. If you remove a scope from the app in HubSpot later, the status does not show it until you reconnect.

Webhooks

HubSpot tells FlowState when a deal is created, deleted, or changed in one of the properties FlowState syncs. This is part of the FlowState app itself and needs no extra scope. It is what lets FlowState send a deal change to AWS within a minute instead of at the next daily sync. See When FlowState reads.

Token storage and security

• FlowState stores your HubSpot authorisation encrypted with your tenant’s own key, and only your tenant can use it. It never writes tokens to logs.
• You can revoke the authorisation at any time in HubSpot: Settings → Integrations → Connected apps → FlowState → Actions → Uninstall. FlowState notices this at its next HubSpot request. Until then the status still shows connected and no email is sent; see Troubleshooting.