Skip to main content
The fastest way to build a Salesive App is to start from the app starter — a complete, runnable sample that already implements the OAuth 2.1 + PKCE install, a signed session, live webhooks over socket.io, and a scoped proxy to the Apps API. It’s a small notes app: a React + Tailwind front end and a Node/Express back end served on one port, so there’s a single thing to run and deploy.
The starter is a learning scaffold, not a framework. Everything is plain, commented code you own and edit — swap the notes UI for your product and keep the install/session/proxy plumbing.

​
Create your app

1

Install the CLI

The starter is scaffolded by the Salesive dev tools CLI.
npm install -g salesive-dev-tools
2

Scaffold the app

create-app clones the starter, seeds .env from .env.example, and prints the next steps.
salesive create-app
# or skip the prompts:
salesive create-app --name my-app --package-manager npm
Prefer not to use the CLI? Clone it directly instead: git clone https://github.com/Eoion/salesive-app-starter my-app — then copy .env.example to .env yourself.
3

Install dependencies

cd my-app
npm install
4

Add your credentials

Create your app in the dashboard (Apps → Developer, see Build & publish) to get a client_id and client_secret, then fill them into .env.
5

Run it

npm run dev
The whole app — UI, API, OAuth, and webhooks — comes up on one port (default http://localhost:3000).

​
Configure

The starter reads everything from .env (copied from .env.example). Only the first three are required to complete an install.
VariableRequiredWhat it is
SALESIVE_CLIENT_IDYesYour app’s client id (app_…), from Apps → Developer.
SALESIVE_CLIENT_SECRETYesYour app’s client secret (sk_…). Server-side only — never ship it to the browser.
SALESIVE_WEBHOOK_SECRETYesSigning secret (whsec_…) used to verify incoming webhooks.
APP_BASE_URLYesPublic URL where your app is reachable. The OAuth redirect_uri is APP_BASE_URL/oauth/callback and must exactly match a redirect URI you registered.
SALESIVE_SCOPESYesComma/space-separated scopes to request at install (the sample uses READ_NOTES,WRITE_NOTES). See Scopes & permissions.
PORTNoPort for the single server (default 3000).
SESSION_SECRETNoDedicated secret for signing the app’s session cookie. Defaults to SALESIVE_CLIENT_SECRET.
MONGODB_URINoSet to persist installs in MongoDB. Unset = zero-config in-memory store.
SALESIVE_API_BASENoSalesive API host. Override only for staging/self-hosted.
.env holds secrets and is git-ignored — never commit it. Only .env.example (placeholders) belongs in source control.

​
Reaching your local app from Salesive

A real install has Salesive redirect the merchant’s browser to your redirect_uri, so localhost only works for installs you trigger from your own machine. For a real install, expose your port with a tunnel (outray, ngrok, cloudflared, …), set APP_BASE_URL to the public HTTPS URL, and register APP_BASE_URL/oauth/callback as a redirect URI in the Developer console.

​
What’s inside

Everything lives on one Express server that also serves the React app (Vite middleware in dev, static dist in prod).
PathResponsibility
server/routes/oauth.jsThe OAuth 2.1 + PKCE install: /oauth/start → consent, /oauth/callback → token exchange.
server/session.jsThe signed, HttpOnly session cookie that proves a browser completed the install — the security anchor.
server/salesive.jsToken exchange, refresh (with rotation), and scoped calls to the Apps API. The app_ token never leaves the server.
server/routes/proxy.jsForwards the app’s /api/* routes to the Apps API with the store-scoped token and pipes the response back.
server/routes/webhooks.jsVerifies the X-Salesive-Hmac-SHA256 signature on incoming webhooks.
server/store.jsWhere installs + tokens live — in-memory by default, MongoDB when MONGODB_URI is set.
src/The React app: install gate, session context, socket.io client, and the notes CRUD UI.

​
Storage

server/store.js ships with two interchangeable backends behind one interface:
  • In-memory (default) — zero setup, but installs are lost on restart. Perfect for trying the starter.
  • MongoDB — set MONGODB_URI to persist installs across restarts and share them between processes.
Swapping in Postgres, Redis, or your own database is just another object with the same handful of methods.

​
Before production

Serve over HTTPS

The session cookie is SameSite=None; Secure, so it’s only sent over HTTPS (localhost aside).

Persist installs, encrypt tokens

Use a real database (set MONGODB_URI) and encrypt the stored app_ tokens at rest.

Verify every webhook

Keep the HMAC signature check and reject unsigned or mismatched deliveries before acting.

Consider App Bridge

For embedded UI, a signed session token survives third-party-cookie blocking better than a cookie. See App Bridge.

​
Next steps

Understand the install flow

The full OAuth 2.1 + PKCE handshake the starter implements.

Pick your scopes

Swap READ_NOTES,WRITE_NOTES for the permissions your app actually needs.

Call the Apps API

Read and write store data through the scoped proxy.

Build & publish

Register your app and list it on the marketplace.