read thedocs.

Sherweb is a cloud marketplace and distribution platform for MSPs, exposed to StackJack through Sherweb's public APIs. It covers your customers, their product catalogs and pricing, platform provisioning (such as Microsoft), subscriptions, orders, and billing.

Connecting Sherweb to StackJack gives your AI assistant a family of 21 sher_ MCP tools — MCP (Model Context Protocol) tools are the standardized commands an AI assistant can call through StackJack. With them, your AI can:

• Review billing — the Distributor payable-charges report (what you owe Sherweb) and per-customer receivable charges (what you bill your customers)
• List customers and read their configured vendor platforms, platform details, and metered usage
• Explore catalogs and pricing — a customer's purchasable catalog, item pricing, the platform directory, platform-required parameters, and product-to-SKU mapping
• Inspect subscriptions — subscription details, pricing, and meters
• Act (on Pro plans) — configure customer platforms, amend or cancel subscriptions, and place orders (always after a no-side-effect validation)

How StackJack authenticates to Sherweb

Sherweb uses OAuth 2.0 client_credentials together with a static subscription key. You provide three values, all created together in the Sherweb Partner Portal under Security → APIs:

• Client ID and Client Secret — the OAuth credentials StackJack exchanges for a short-lived access token.
• Subscription Key — an API gateway key sent on every call as the Ocp-Apim-Subscription-Key header, in addition to the OAuth token. A missing or wrong subscription key fails authentication even with a valid Client ID and Secret.

There is no per-user sign-in — all AI traffic authenticates with this single partner credential set.

Two API families: Distributor and Service Provider

Sherweb splits its API into two families, and your credentials are entitled to one or both depending on your partner agreement:

• Distributor (production) — the payable-charges billing report (sher_get_payable_charges).
• Service Provider (Beta) — everything else: customers, catalogs, platforms, subscriptions, and orders.

StackJack automatically requests the right access for each tool. If a tool returns a 403, your credentials are most likely not entitled to that tool's API family (or lack that scope) — contact Sherweb to adjust your entitlements. A key entitled to only one family still works for that family's tools.

Service Provider is in Sherweb Beta. Sherweb labels the Service Provider API as Beta, so its response shapes may change over time.

Before you begin

• In StackJack: you need a role that can manage connectors (tenant Owner, a co-owner, or an Administrator).
• In Sherweb: you need administrator access to the Sherweb Partner Portal sufficient to create an API application under Security → APIs.

Step 1 — Create API credentials in Sherweb

1. Sign in to the Sherweb Partner Portal as an administrator and go to Security → APIs.
2. Create a new API application. Sherweb issues a Client ID, a Client Secret, and a Subscription Key.
3. Confirm which API families your application is entitled to (Distributor and/or Service Provider) — this determines which tools will work.
4. Record all three values — you'll paste them into StackJack.

Step 2 — Add the credentials in StackJack

1. In the StackJack portal, open Connectors.
2. Find the Sherweb card. Click How To Connect for the same steps inline, or Configure to enter the credentials.
3. Enter the Client ID, Client Secret, and Subscription Key. No URL is required — Sherweb's API host is fixed.
4. Click Save.

What happens when you save

• All three values are stored encrypted in Azure Key Vault — never in the StackJack database, and never shown back to you.
• If this is the first time you configure Sherweb, a Free-tier subscription for the connector is created automatically so its Free tools work right away.
• StackJack immediately live-validates the credentials by acquiring a token and calling a cheap authenticated read (a Service Provider platforms read, falling back to the Distributor billing read for a Distributor-only key). Validation never blocks the save: you'll either see a success confirmation or a "saved but validation failed" warning with the reason.
• The connector card shows the current connection and validity status from then on.

Asynchronous operations

Some Service Provider actions — subscription amendments, subscription cancellations, and orders — complete asynchronously. They return a tracking id. Your AI polls sher_track_request with that id until the status reaches Success or Failure (the intermediate states are Queued and Processing).

Plans and available tools

• Free includes the 17 read-only tools: billing reports, customer and platform reads, catalog and pricing lookups, and subscription details, pricing, and meters. (Several of these are query endpoints that take a request body but only read data.)
• Pro adds the 4 write/action tools: configure customer platforms, amend subscriptions, cancel subscriptions, and place orders.
• Business offers the same tool set as Pro with a higher monthly call quota.

Sherweb has no per-user OAuth, so there is no per-user attribution — all AI traffic authenticates as the single partner credential set. Current pricing and quotas are shown in the portal's Billing page and at checkout.

Safety note — cancelling subscriptions. sher_cancel_subscriptions is marked destructive: cancelling may end a customer's service and cannot be undone through this API. Scope your AI's access to write tools deliberately — use the tool selections on the MCP Setup page and the Permissions page to enable only the actions you want an AI to take. Always run sher_validate_place_order before sher_place_order to catch cart problems without placing a real, billable order.

Rate limits

Sherweb's APIs are fronted by an API gateway. StackJack paces requests conservatively per tenant and honors any 429 backoff, so bursts of tool calls queue briefly instead of failing — a long read may simply take a little longer.

Rotating or replacing the credentials

The Client ID, Client Secret, and Subscription Key are the recovery secret. If you regenerate any of them in the Sherweb Partner Portal, the stored credential becomes invalid. To restore access, open Connectors → Sherweb → Configure in StackJack, enter the new values, and Save.

Troubleshooting