Appearance
Funnel SDK
The Funnel SDK is the client-side API that runs published funnels: runtime identity, events, uploads, checkout, payments, and the user and subscription operations a funnel or an app login needs. It authenticates with the project's publishable key, so it can run in a browser or a mobile app.
Server-to-server capabilities that do not serve funnel execution — backend funnel-user reads, transaction search, subscription mutations and email — belong to the API reference and authenticate with a project secret key or an API key.
To display a hosted paywall inside your web app, follow Embed a Web Paywall. It covers the browser SDK, FG user ID or email, and returning to your app after checkout.
Base URL:
text
https://sdk-api.funnelsgrove.comGet SDK keys
Open the funnelsgrove dashboard, select your project, then open Project Settings. Copy the SDK publishable key for Funnel SDK calls. For trusted backend calls to the API, create an API key in Organization Settings → API Keys; older projects can also use the SDK secret key shown in Project Settings. See Authentication.
The publishable key is safe to expose in browser or mobile app code. API keys and the secret key are not; store them only on your backend.
Key rotation behavior:
| Key | Used by | Rotation behavior |
|---|---|---|
| SDK publishable key | Funnel SDK | Old key keeps working for 30 days. |
| SDK secret key (older projects) | API | Old key stops working immediately. |
| API key | API | Revoke it and create a new one; the old key can keep working for up to one minute. |
Which API
| API | Auth header | Use for |
|---|---|---|
| Funnel SDK | X-SDK-Publishable-Key | Funnel sessions, checkout, access checks, and App Login. |
| API | Authorization: Bearer <key> or X-SDK-Secret-Key | Backend user reads, transaction search, subscription mutations and email. |
Required IDs
Most funnel-runtime requests include funnelId. App access verification can instead resolve a user across the project through the SDK publishable key. Verified-email lookup returns the funnelsgrove user_id; save that opaque ID on the authenticated account and use it for subsequent subscription checks and login tracking.
For App Login, call POST /sdk/public/users/verify_subscription with a known userId or verified email. When a user resolves, record the verified login through POST /sdk/public/users/track_login, regardless of subscription status. Save the exact returned ID. Verification is read-only; login tracking does not grant paid access. See the integration guide for the full flow.
Reference by task
- Public API: identity, app access, runtime methods, and uploads.
- Payments: checkout, verification, upsells, and subscriptions.
- Errors & retries: budgets, cancellation, recovery, and proxy headers.