App Installer Details API for the Sparkforge Marketplace

The App Installer Details API gives Marketplace developers verified installer identity, install context (sub-account and agency), and white-label branding so you can personalize onboarding, theme your UI, and reach the agency owner — all on minimal OAuth scopes.

Why this endpoint exists

• Identity and context: who installed and where the app lives
• White-label awareness: agency branding fields for in-app theming
• Scope reduction: avoids broad company-level OAuth scopes for branding data
• Personalized onboarding: agency-specific welcome flows, content, and pricing
• Owner outreach: contact details to build agency relationships
• Privacy by design: respects white-label boundaries between agencies and sub-accounts

Authentication

Supported tokens: Agency Token or Sub-account Token.

• An Agency Token resolves installer + agency context, and can indicate the sub-account where the install occurred.
• A Sub-account Token resolves installer + the current sub-account's agency context.

Headers:

Authorization: Bearer {YOUR_TOKEN}
Content-Type: application/json

Use the least-privileged token for the runtime context. A sub-account workflow should use a Sub-account Token rather than an Agency Token.

Endpoint

HTTP method: GET

Path: /marketplace/app-installer/details (placeholder — confirm in the official API reference).

cURL example:

curl -X GET \
  "{BASE_URL}/marketplace/app-installer/details" \
  -H "Authorization: Bearer {AGENCY_OR_SUB_ACCOUNT_TOKEN}" \
  -H "Content-Type: application/json"

Response fields

• installer.userId (string) — unique ID of the installer
• installer.name (string) — human-readable name
• installer.email (string) — contact for collaboration and account linking
• installationContext.subAccountId (string|null) — sub-account where installed
• installationContext.agencyId (string) — parent agency ID
• agency.companyName, agency.companyEmail, agency.ownerName
• whiteLabel.brandName, whiteLabel.supportEmail, whiteLabel.supportUrl, whiteLabel.primaryDomain, whiteLabel.logoUrl, whiteLabel.faviconUrl

White-label data guidance

• Use brandName, logoUrl, and primaryDomain to theme your app UI for agency users.
• Don't leak agency identity to sub-account end clients unless explicitly intended.
• Server-side cache branding fields with a short TTL (15-60 minutes) to reduce calls and pick up updates.
• Invalidate the cache when a new logoUrl or brandName is detected.

Rate limiting and caching

• Cache installer + white-label result per token/context. Refresh on login or session start.
• Use exponential backoff with jitter on 429/5xx responses.
• Don't call this endpoint on every page — once per session or context change is plenty.

Error handling

Setup steps

1. Generate Agency and Sub-account tokens for testing. Store them in a vault or secrets manager.
2. Implement a GET to {BASE_URL}/marketplace/app-installer/details with the appropriate Bearer token.
3. Persist installationContext and agency IDs. Cache whiteLabel fields. Hydrate UI theme from whiteLabel and welcome copy from installer.name.
4. Add 401/403/404/429 handlers and exponential backoff. Don't expose raw JSON to end clients.
5. Confirm agency branding isn't leaking to unintended sub-account audiences.
6. Add observability: success rate, latency, cache hit ratio.

FAQ

Which token should I use?

Match the token to your runtime context. Agency tokens resolve agency + installer (and can reference sub-account installs). Sub-account tokens resolve the current location's agency context.

Does this require company-level OAuth scopes?

No. Avoiding broad company-level scopes is a primary reason the endpoint exists.

Can I cache the response?

Yes. Cache per token/context and refresh on session start or branding change.