Marketplace App Distribution Types and OAuth Token Flow

By Sparkforge Support Team ·Last reviewed May 3, 2026

Marketplace apps are configured by three fields: target user (Agency or Sub-account), who can install, and bulk install support. Each combination maps to a specific OAuth token flow and reseller behavior.

This developer guide covers the Marketplace distribution model and the OAuth flow you need to pick the right access token for your app.

Distribution model fields

Three fields determine how your app is listed and installed:

Field	Values	What it controls
Target user	Agency / Sub-account	Whose access token your app needs. For ~95% of apps this is Sub-account. Cannot be changed once set.
Who can install	Both Agency and Sub-account / Agency Only	Which users see and install the app from the Marketplace. Both gives maximum reach. Use Agency Only for fully white-labelled SaaS features.
Bulk install	Yes / No	Whether agency owners can install your app to many sub-accounts in one operation. New apps must be set to Yes. Cannot revert from Yes to No.

Private app install limits

If your Marketplace app is set to App type = Private:

Cap: a Private app can be installed in up to 5 Agencies.
Block: at 6+ Agencies, new installs are blocked until you either publish the app as Public or pass Security Review.

Counting rules

Each unique Agency counts as 1, regardless of how many sub-accounts (locations) the app reaches.
Bulk installs still count as 1 per Agency.
Counts update in real time when an app is fully uninstalled from an Agency.

Distribution scenarios and the right access token

Target user	Who can install	Bulk install	Installer	Token signature
Agency	NA	NA	Agency user	`isBulkInstallation: false`, `userType: Company`
Sub-account	Agency & sub-account	No	Sub-account user	`isBulkInstallation: false`, `userType: Location`
Sub-account	Agency & sub-account	No	Agency user	`isBulkInstallation: false`, `userType: Location`
Sub-account	Agency & sub-account	Yes	Sub-account user	`isBulkInstallation: false`, `userType: Location`
Sub-account	Agency & sub-account	Yes	Agency user (recommended)	`isBulkInstallation: true`, `userType: Company`
Sub-account	Agency Only	Yes	Agency user	`isBulkInstallation: true`, `userType: Company`

For the bulk install case (recommended), follow this flow:

Get the list of sub-accounts where the app is installed.
For each location, exchange the Agency Token for a Location Token.
Listen for the AppInstall webhook so future installs (including SaaS plan auto-installs) trigger the same token exchange.

Backward compatibility for legacy apps

Existing apps map to the new model so the original install flow keeps working.

Legacy type	Target user	Who can install	Bulk install	Path to maximum reach
Agency Only	Agency	NA	NA	No change.
Sub-account Only	Sub-account	Agency & sub-account	No	Build the bulk-install token exchange, then flip bulk install to Yes.
Agency & Sub-account	Sub-account	Agency Only	Yes	Drop agency-level scopes, build a sub-account OAuth flow that returns a `userType: Location` token, then change install scope to Agency & sub-account.

Agency-level scopes that block sub-account install include companies.readonly, companies.write, location.write, saas/location.write, snapshots.readonly, snapshots.write, custom-menu-link.readonly, custom-menu-link.write, plus the Snapshots and CustomJS modules.

Distribution types in detail

Target user: Agency

Use this when the app's functionality only applies at the agency level.

Listing: agency-level Marketplace only.
Install: agency admins or owners only.
Payments: the installing agency pays.
Re-selling: not available.

Target user: Sub-account, both can install

The right pick when sub-accounts are the end users.

Listing: both agency and sub-account Marketplaces.
Install: sub-account admins or agency admins.
Bulk install: if the developer enables it, agencies can mass-install or set the app to install automatically for all future sub-accounts.
Payments: the installing sub-account pays.
Re-selling: agencies can re-sell to their sub-accounts.

Target user: Sub-account, only agency can install

Use when only agency owners should be able to deploy the app to their sub-accounts.

Listing: agency Marketplace only.
Install / uninstall: agency admins or owners only, including at the sub-account level.
Bulk install: available if enabled by the developer.
Re-selling: agencies can re-sell. The developer sets the base price; the agency sets a marked-up price for sub-accounts.

Frequently Asked Questions

Which target user should I pick?

Sub-account fits about 95% of apps. Pick Agency only when the functionality genuinely operates at the agency level.

Can I change the target user later?

No. Target user is locked once set. Plan it carefully before submitting your app.

What happens when a Private app hits 6 Agencies?

New installs are blocked. To unblock, either publish the app as Public or pass Security Review while keeping it Private.

How does bulk install change the OAuth flow?

Agency users installing in bulk receive a Company-type token. You then exchange it for Location tokens per sub-account and listen to the AppInstall webhook for future installs.

Can sub-accounts re-sell apps to other sub-accounts?

No. Re-selling is an agency-to-sub-account capability, available on Sub-account distribution types.