How to Get Started with the Sparkforge Developer Marketplace

The Sparkforge Developer Marketplace exposes the platform's APIs through OAuth 2.0. You can build public apps for the Marketplace listing, private apps limited to your own agency, or vendor integrations with sub-account scope. This guide covers the OAuth flow, app registration, and webhook setup.

Distribution and access levels

• Sub-Account / Location level — operations scoped to a single sub-account. Pass the location ID with each call.
• Agency / Company level — operations across every sub-account in the agency.
• Public app — listed in the Marketplace, installable by any qualifying account.
• Private app — invite-only, capped at 5 unique agency installs. To go beyond 5 you publish public or request a security review.

OAuth 2.0 flow

1. Register. Create an app in the Marketplace with name, type, distribution, and scopes. You receive a Client ID and Client Secret.
2. Authorize. Redirect the user to the Marketplace authorization URL with your Client ID, scopes, and redirect URI.
3. Consent. The user signs in and approves. The Marketplace redirects back to your URI with an authorization code in the query string.
4. Exchange. Your server POSTs the code, Client ID, Client Secret, grant type, and redirect URI to /oauth/token. You get back an access token, refresh token, and expiration.
5. Call. Include Authorization: Bearer {access_token} on every API request. The token's scopes determine what calls succeed.
6. Refresh. When the access token expires, exchange the refresh token for a new one without involving the user.

OAuth 2.0 with PKCE

Public clients (browser apps, mobile apps) and providers that require PKCE add a code_challenge and code_challenge_method=S256 to the auth request, then send the matching code_verifier on the token exchange. Configuration details: marketplace.sparkforge.com/docs/oauth/ExternalAuthentication.

Step-by-step: build your first app

1. Sign up at marketplace.sparkforge.com.
2. In My Apps, click Create App. Fill in name, type (public or private), and distribution (agency or sub-account).
3. Add the scopes your app needs. Reference the Scopes doc — request the minimum set, not everything.
4. Generate client credentials. Save the Client ID and Client Secret in a vault.
5. Build a GET endpoint at, e.g., /oauth/callback/sparkforge. It pulls the code query param, POSTs to the token endpoint, and stores the access and refresh tokens.
6. Set the OAuth Redirect URL in your app settings to that endpoint.
7. Build a POST endpoint to receive webhook events. The body is JSON.
8. Set the webhook URL in your app settings.

Install and connect a webhook

1. Sign in as an agency admin.
2. Open your app in the Marketplace, click + Add App, pick the target sub-account or location.
3. You'll be redirected back with code=... in the URL.
4. Open YOUR_REDIRECT_URL?code=CODE to trigger the token exchange.
5. If the response from the token endpoint includes an access token, the webhook is connected.

Common API operations

• Contacts CRUD, search, and tags
• Conversations and messages (email, SMS, chat)
• Forms and form submissions
• Custom fields and custom values
• Email and SMS templates
• Opportunities and pipelines
• Calendars, appointments, and tasks
• Orders, customers, and invoices
• Workflows (create, update, trigger)
• Snapshots

Sell on Marketplace

When an agency admin clicks Sell on Marketplace, Sparkforge auto-creates a developer profile in the background using the existing account, prompts the admin to set a password, accept developer terms, and verify a one-time email code, then signs them into the new developer account. No separate signup form.