curl -X POST $KS/v1/admin/licenses/$LICENSE_ID/change-tier \
-H "Authorization: Bearer ks_..." \
-d '{
- "target_policy_slug": "pro",
+ "to_policy_slug": "pro",
+ "skip_payment": true,
"reason": "support resolution"
}'
- Always applies as comp (no invoice) from the admin path. Buyer-initiated paid upgrades go through /v1/upgrade (different endpoint, signed-license auth).
Scope required: licenses:write.
With skip_payment: true this applies as a comp (no invoice). Omit it (defaults to false) and the admin path behaves like the buyer path: it creates an invoice for the prorated charge and returns the checkout URL. Buyer-initiated paid upgrades go through /v1/upgrade (different endpoint, signed-license auth).
Master admin key required.
On a sandbox daemon (KEYSAT_SANDBOX_MODE=1), a scoped key carrying payment_providers:write can connect a BTCPay store over the API with no browser step, as long as the store settles on a non-mainnet network (regtest / testnet / signet). On a production daemon, or for a mainnet store, connect stays master-only. This is the path a delegated setup agent uses to stand up a disposable test instance end to end. You need a BTCPay API key for the target store (the operator's BTCPay access, delegated to you) carrying the same store and invoice permissions the browser flow grants (see Install & setup): the store-settings permissions complete the connect, and the invoice permissions let settled purchases issue licenses.
List endpoints return up to ~100 rows by default. Use ?limit=N and ?offset=N for larger result sets. The OpenAPI spec documents the limits per endpoint.
The admin endpoints have no per-IP rate limit today. Operators are trusted. The public endpoints (/v1/validate, /v1/recover) are rate-limited per client IP (10/min for /recover; /validate is unlimited but a reasonable agent calls it once per app boot + once per hour).
The admin endpoints have no per-IP rate limit today. Operators are trusted. The public endpoints (/v1/validate, /v1/recover) are rate-limited per client IP (10/min for /recover; /validate allows a 60/min burst per client IP, which a reasonable agent stays well under by calling it once per app boot + once per hour).
If your automation needs full-admin because it touches operator-only operations (creating other API keys, changing payment providers), use the master key from a secret manager. If it can stay within license / product / policy operations, always use a scoped key. Operators can revoke a compromised scoped key without rotating the master credential.
keysat_x86_64.s9pk from the GitHub releases page.keysat.s9pk from the GitHub releases page.BTCPay Server is declared as a required dependency. If you don’t have it installed yet, StartOS will prompt you to install it as part of the same flow.
Open the Keysat service page in StartOS. Go to Actions → Set operator name. Pick a short label that identifies you as the seller, e.g. "aurora-software", "northpath", "my-name". This shows up on the public purchase pages and in the audit log.
+Open the admin web UI (Step 5) and go to Settings. Set your operator name there: a short label that identifies you as the seller, e.g. "aurora-software", "northpath", "my-name". This shows up on the public purchase pages and in the audit log.
This change is live-reloaded; you don’t need to restart the service.
Make sure BTCPay Server is running and has at least one store with a configured payment method (on-chain wallet or Lightning node). Without a payment method, BTCPay will reject Keysat’s invoice creation.
-In Keysat’s service page, click Actions → Connect BTCPay. You’ll be redirected to BTCPay’s authorize page, where you grant Keysat the permissions it needs:
+In the admin web UI, go to Settings → Payment providers and click Connect BTCPay (agents can drive the same connect over the API with POST /v1/admin/btcpay/connect). You’ll be redirected to BTCPay’s authorize page, where you grant Keysat the permissions it needs:
btcpay.store.canviewstoresettingsConnect is idempotent. If you click it again later, Keysat detects the existing connection and returns success without re-authorizing. To force a re-authorize, run the Disconnect BTCPay action first.
+Connect is idempotent. If you click it again later, Keysat detects the existing connection and returns success without re-authorizing. To force a re-authorize, disconnect first from Settings → Payment providers (or POST /v1/admin/btcpay/disconnect).
Automating setup? On a sandbox daemon you can connect a non-mainnet BTCPay over the API instead of clicking, using a scoped key carrying the payment_providers:write scope. See Agent integration: Connect BTCPay programmatically.
Click Actions → Check BTCPay connection to verify the wiring. It should report:
+Back in Settings → Payment providers (or via GET /v1/admin/btcpay/status), verify the wiring. It should report:
# Expected output: status: connected @@ -120,7 +120,7 @@ payment_methods: [BTC-OnChain, BTC-LightningNetwork]If
payment_methods is empty, head back to BTCPay and configure at least one before continuing.
Go to Actions → Show admin API key. This reveals the 64-hex-character key that gates all /v1/admin/* endpoints, including the admin UI.
Go to Actions → Show credentials. This reveals the 64-hex-character admin API key that gates all /v1/admin/* endpoints, including the admin UI.
Click the Launch UI button on Keysat’s service page. (StartOS surfaces this for any service that defines a type: 'ui' interface.) Paste the admin key from the previous step into the sign-in form.
From here on, you mostly work in the admin UI. The StartOS Actions tab is reserved for setup-only operations (operator name, BTCPay connect/disconnect/check, show admin key).
+From here on, you work in the admin UI. The StartOS Actions tab is reserved for the few operations that must happen outside the web UI: showing credentials, setting the web UI password, and activating or checking the Keysat self-license.
In the admin UI, go to Products → Create a new product and fill in: