From 7e6f7524621ab72de6f492558f36c7189d7a82ca Mon Sep 17 00:00:00 2001 From: Keysat Date: Wed, 17 Jun 2026 09:32:21 -0500 Subject: [PATCH] Document agent BTCPay connect (sandbox, scoped key) Add the "Connect BTCPay programmatically" agent workflow and a payment_providers:write extra-scope note to agent.html; correct the "not exposed to agents" section to the accurate gate (scoped connect is sandbox + non-mainnet only; disconnect and production/mainnet stay master-only). Fix the BTCPay permission list in install.html to the five permissions the daemon actually requests, and point operators at the agent path. --- agent.html | 29 ++++++++++++++++++++++++++--- install.html | 6 +++++- 2 files changed, 31 insertions(+), 4 deletions(-) diff --git a/agent.html b/agent.html index c67a160..a6a94e2 100644 --- a/agent.html +++ b/agent.html @@ -88,7 +88,10 @@ curl https://your-keysat-host/v1/admin/licenses?status=active \ full-adminEvery scope. Equivalent to the master key for most endpoints. -

Endpoints that touch settings (operator name, payment provider connections, self-license activation, scoped API key management) always require the master admin key. A full-admin scoped key cannot, for example, generate another scoped key. That's a self-defeating elevation path.

+

Endpoints that touch settings (operator name, self-license activation, scoped API key management) always require the master admin key. A full-admin scoped key cannot, for example, generate another scoped key. That's a self-defeating elevation path.

+ +

A-la-carte extra scopes

+

An operator can grant a single sensitive capability on top of a role when minting a key (admin UI → Settings → API keys). The only one today is payment_providers:write, which lets a scoped key connect a BTCPay payment provider, but only on a sandbox daemon and only for a non-mainnet network (see Connect BTCPay programmatically). It belongs to no role by default (not even full-admin): a credential that can repoint where settlement lands is a fund-redirection key, so on a production daemon connecting a provider always stays master-only.

Discovering the API

Two complementary discovery mechanisms.

@@ -248,6 +251,26 @@ curl -X POST $KS/v1/admin/subscriptions/$SUB_ID/cancel \

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.

+

Connect BTCPay programmatically (sandbox)

+

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.

+ 
# 1. Start the connect. Returns a one-time `state` token + the BTCPay authorize URL.
+curl -X POST $KS/v1/admin/btcpay/connect \
+  -H "Authorization: Bearer ks_..."
+# -> { "authorize_url": "https://btcpay.example/api-keys/authorize?...", "state": "STATE", "merchant_profile_id": "..." }
+
+# 2. Complete the connect by handing Keysat your BTCPay store API key, keyed by the
+#    `state` token (no Authorization header here: the single-use state token is the tie).
+#    A human approving in the browser at authorize_url reaches this same callback.
+#    Keysat resolves the store's network here and returns a 4xx if it is mainnet.
+curl "$KS/v1/btcpay/authorize/callback?state=STATE&apiKey=BTCPAY_STORE_API_KEY"
+# -> "BTCPay connected successfully."  (HTTP 4xx with an error page if the gate refuses)
+
+# 3. Confirm.
+curl $KS/v1/admin/btcpay/status -H "Authorization: Bearer ks_..."
+# -> { "connected": true, "store_id": "...", "base_url": "...", ... }
+

Scope the BTCPay key to exactly the store you want to connect: Keysat attaches the first store the key can see. If the store's network cannot be confirmed as non-mainnet (mainnet, a Lightning-only store, or any detection failure), the callback fails closed with a 4xx and nothing is persisted. Disconnect (POST /v1/admin/btcpay/disconnect) is always master-only.

+

Scope required: payment_providers:write, on a sandbox daemon, for a non-mainnet store. The master key may connect any network on any daemon.

+

Worked example: gate an app behind a license

End to end, with nothing but a merchant-onboard scoped key and the SDK: stand up a product, issue a license, and gate a feature in a Next.js app. No payment provider is needed for this path (you're issuing comp/dev licenses by hand; wiring BTCPay so buyers can self-checkout is covered in Install & setup). This is the minimal true path, nothing more.

@@ -377,13 +400,13 @@ def issue_comp_license(buyer_email: str, product_slug: str, reason: str) -> str:

Some operations are deliberately operator-only and not accessible to any scoped key, including full-admin:

-

These all require the master KEYSAT_ADMIN_API_KEY. The reasoning: an agent that can rotate its own credentials, connect arbitrary payment processors, or change the operator identity is no longer bounded by the role it was given.

+

These require the master KEYSAT_ADMIN_API_KEY. The reasoning: an agent that can rotate its own credentials, repoint settlement to an arbitrary wallet, or change the operator identity is no longer bounded by the role it was given. The one deliberate carve-out is sandbox payment-provider connect (above): bounded to a sandbox daemon and a non-mainnet network, it lets a delegated agent stand up a disposable test instance end to end without ever touching mainnet funds or the master key.

Help us improve this guide

The OpenAPI spec is the source of truth for the API surface. This guide is a hand-curated overlay focused on the workflows we've seen agents actually need. If you're building something the spec covers but this guide doesn't make obvious, open an issue at github.com/keysat-xyz/keysat with the workflow shape and we'll add it.

diff --git a/install.html b/install.html index 5473d8d..eb69ab4 100644 --- a/install.html +++ b/install.html @@ -88,9 +88,11 @@

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:

Once you confirm, BTCPay redirects back to Keysat with an API key and store id. Keysat:

@@ -105,6 +107,8 @@

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, run the Disconnect BTCPay action first.

+

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:

# Expected output: