SubSovereign
← All guides

Getting started with SubSovereign

This guide takes you from nothing to a working subscription check in your app. It's the practical companion to How SubSovereign works — read that first if you want the concepts.

There are five steps: stand up the server → create your app → define what you sell → add the SDK → check access. Budget an afternoon for the first one; the rest are quick.

Step 1 — Stand up the server

SubSovereign is self-hosted, so the first step is to run the backend on your own infrastructure. It's a Node.js/TypeScript service backed by PostgreSQL (for entitlements, events, and consent) and Redis (for a fast entitlement cache).

cd backend
cp .env.example .env
# Fill in every value in .env — database URL, store credentials, secrets.

npm install
npm run migrate      # creates the database tables
npm run build && npm start

For a managed deployment there's a ready-made Northflank config (backend/northflank.yml), but any host that runs Node + PostgreSQL + Redis works — the point is that it's yours. Once it's up, note its address; that's the baseUrl your apps will talk to (e.g. https://subs.yourdomain.com).

Tip: keep the server on UK/EU hosting. Sovereignty and GDPR are the whole point — don't give that away at the deployment step.

Step 2 — Create your app in the dashboard

Open the dashboard and create an app — one per product you ship (your Android app and iOS app can be the same app record, or separate; your call). Creating an app gives you two things you'll need:

  • an appId — identifies this app to the server, and
  • an API key — the credential your app uses to authenticate its SDK calls.

🚩 Copy the API key the moment it appears, and store it somewhere safe. It is shown once. We keep only a hash of it, so it cannot be shown again, and a replacement key cannot be issued for an app that already exists. If you lose it, archive that app and create a new one — see Archiving an app below.

Step 3 — Define what you sell

Still in the dashboard, set up the things your users will actually buy:

  1. Create your access levels (also called tiers) — the levels of access your product grants, such as free or premium. These names are yours to choose and are separate from your store product IDs (next step); your app checks against these.
  2. Link each store product to an access level. In each store (App Store, Google Play, Amazon, Roku, Stripe) you create the subscription products as normal; in SubSovereign you tell it "this store product grants this access level." The product IDs must match your store exactly, and several products can map to one tier — e.g. an annual premium and a premium_lifetime product both granting the premium tier. That mapping is what turns a purchase into an entitlement.
  3. Design your paywall — the headline, features, prices, and trial lengths. Because this is served remotely, you can change it later without shipping an app update.

Step 4 — Add the SDK to your app

Drop the SDK into your app and point it at your server. The shape is identical on every platform — follow the guide for yours:

Each one configures the SDK once with your apiKey, appId, your server baseUrl, and a stable userId for the signed-in user (use the same ID everywhere so access follows the user across devices).

Step 5 — Check access and go live

With the SDK configured, your app does two things:

  • On launch, ask what the user has and unlock accordingly (the Android guide shows this as checkEntitlements(); every SDK has the equivalent).
  • After a purchase, hand the receipt to SubSovereign so the server validates it with the store and grants the access level — then re-check, and unlock.

That's a working integration. Before you ship, a quick checklist:

  • Server deployed on UK/EU hosting, migration run, reachable from your app.
  • App created; API key stored safely; the app points at your baseUrl.
  • Access levels defined and linked to real store products in every store you support.
  • Store billing (Google Play / StoreKit / Amazon / Roku / Stripe) working in your app.
  • Entitlement check on launch; receipt validation after purchase; both tested on a real device with a real (sandbox) purchase.
  • GDPR consent recorded where you collect it.

Archiving an app

Apps are never deleted — they are archived. That is a deliberate design decision, not a missing feature.

An app owns your subscribers' entitlements, their statutory cooling-off windows, your compliance records and the audit trail. Deleting it would revoke access for every paying subscriber and destroy records you are required to keep under GDPR Art. 17(3)(b). So there is no delete, and there will not be one.

What archiving does:

  • removes the app from your list — Show archived brings it back
  • revokes its SDK keys, so the app stops answering
  • frees an app slot, so you can create another within your plan
  • keeps every row — subscribers, entitlements, compliance events, audit trail

It refuses while anyone is still subscribed. If the app has live subscribers you get a message saying how many, and nothing changes. Archive it once they have ended, so nobody loses access they are still paying for.

Restoring puts the app back, and is capped like creating one — if you are already at your plan's app limit you will need to archive something else first. 🚩 Keys are not restored. They were revoked when you archived, and revocation is one-way: issue a new key from a new app.

If you have lost an API key

You cannot reissue one for an existing app. Archive that app — which frees the slot — and create a replacement. Nothing is lost: the archived app keeps all its records, and you can restore it later if you need to read them.

Archiving a tenant (operators)

The same applies one level up, on the Tenants page. Archive is not Suspend, and both exist:

  • Suspend — a temporary block on a live customer you expect back
  • Archive — end-of-life filing

Archiving a tenant archives its apps and revokes their keys, and refuses while any of its apps has a live subscriber. Restoring the tenant brings it back but leaves its apps archived, so the plan's app cap still applies and you restore only the ones you still want.

Where to go next

Also in:EnglishDeutschEspañolFrançaisहिन्दीItaliano한국어NederlandsPolskiPortuguês