App starter - Salesive Docs

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

Install the CLI

The starter is scaffolded by the Salesive dev tools CLI.

npm install -g salesive-dev-tools

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.

Install dependencies

cd my-app
npm install

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.

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.

Variable	Required	What it is
`SALESIVE_CLIENT_ID`	Yes	Your app’s client id (`app_…`), from Apps → Developer.
`SALESIVE_CLIENT_SECRET`	Yes	Your app’s client secret (`sk_…`). Server-side only — never ship it to the browser.
`SALESIVE_WEBHOOK_SECRET`	Yes	Signing secret (`whsec_…`) used to verify incoming webhooks.
`APP_BASE_URL`	Yes	Public 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_SCOPES`	Yes	Comma/space-separated scopes to request at install (the sample uses `READ_NOTES,WRITE_NOTES`). See Scopes & permissions.
`PORT`	No	Port for the single server (default `3000`).
`SESSION_SECRET`	No	Dedicated secret for signing the app’s session cookie. Defaults to `SALESIVE_CLIENT_SECRET`.
`MONGODB_URI`	No	Set to persist installs in MongoDB. Unset = zero-config in-memory store.
`SALESIVE_API_BASE`	No	Salesive 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).

Path	Responsibility
`server/routes/oauth.js`	The OAuth 2.1 + PKCE install: `/oauth/start` → consent, `/oauth/callback` → token exchange.
`server/session.js`	The signed, HttpOnly session cookie that proves a browser completed the install — the security anchor.
`server/salesive.js`	Token exchange, refresh (with rotation), and scoped calls to the Apps API. The `app_` token never leaves the server.
`server/routes/proxy.js`	Forwards the app’s `/api/*` routes to the Apps API with the store-scoped token and pipes the response back.
`server/routes/webhooks.js`	Verifies the `X-Salesive-Hmac-SHA256` signature on incoming webhooks.
`server/store.js`	Where 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.

​Create your app

​Configure

​Reaching your local app from Salesive

​What’s inside

​Storage

​Before production

Serve over HTTPS

Persist installs, encrypt tokens

Verify every webhook

Consider App Bridge

​Next steps

Understand the install flow

Pick your scopes

Call the Apps API

Build & publish

Create your app

Configure

Reaching your local app from Salesive

What’s inside

Storage

Before production

Next steps