Connect Sherweb

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…

Written By Christopher Scaminaci

Last updated 6 days ago

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 focused family of 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. Sherweb's public guide directs partners to Partner Portal → Security → APIs for API keys, and StackJack's shipping integration requires three values from that registration:

Client ID and Client Secret — the OAuth credentials StackJack exchanges for a bearer token. StackJack caches and renews bearer tokens automatically; you never paste an 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 scope families. The token endpoint requires distributor, service-provider, or both, and the APIs available to your application depend on its Sherweb configuration and 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 matching scope for each tool. If a tool returns a 403, the application or partner account most likely lacks that API family or operation; contact Sherweb to confirm access. A credential set that works for only one family can still validate and use 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

Sign in to the Sherweb Partner Portal as an administrator and go to Security → APIs.
Create or open the API registration that StackJack should use and collect its Client ID, Client Secret, and Subscription Key.
Confirm whether the registration can request the distributor scope, the service-provider scope, or both. This determines which tool families can succeed.
Store all three values securely. Sherweb's public guide does not document whether an existing client secret can be displayed again; if the portal no longer reveals it, issue a replacement instead of guessing.

Step 2 — Add the credentials in StackJack

In the StackJack portal, open Connectors.
Select the Sherweb card. Choose How To Connect for the inline checklist or Configure to enter credentials.
Enter the Client ID, Client Secret, and Subscription Key. No URL is required — Sherweb's API host is fixed.
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 performs side-effect-free validation by acquiring a token and reading Service Provider platforms. If that family rejects the credential, StackJack tries the Distributor payable-charges read so a Distributor-only credential can still validate.
Validation does not discard a credential that Sherweb rejects. A successful probe shows Connected. A failed probe shows Needs Attention with the upstream reason and a Re-test action.

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).

Collection and language behavior

Sherweb's published endpoints do not expose a common page, offset, or cursor parameter, so StackJack does not invent one: list operations return the collection Sherweb sends in that response. Avoid scheduling multiple full-customer or catalog inventories at the same time.

Where a tool offers acceptLanguage, use en or fr. StackJack sends it as Accept-Language; omitting it leaves Sherweb's default language in effect.

Plans and available tools

Free includes 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 actions to configure customer platforms, amend subscriptions, cancel subscriptions, and place orders.
Business offers the same tool set as Pro with a higher monthly call quota.

See the generated Sherweb tool reference for the current inventory, plan assignment, input schemas, and destructive-action labels.

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 public API documentation does not publish one general numeric quota. StackJack applies an aggregate limit of about 120 requests per minute per tenant and records API-gateway 429 responses so later calls back off. That local guard is not a promise of Sherweb capacity: reduce concurrency and retry after a short delay if the gateway continues throttling.

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.

Disconnecting Sherweb

Use Disconnect in the Sherweb drawer to remove StackJack's stored Client ID, Client Secret, and Subscription Key and stop future Sherweb API calls. Disconnecting does not revoke the API registration in Sherweb and does not reverse platform configuration, subscription amendments/cancellations, or orders already submitted. Disable or rotate the keys separately in Sherweb if they should no longer work anywhere.

For a Free subscription, the confirmation can also remove Sherweb tools from tool lists. A paid connector plan remains separate billing state; use Manage on Billing on the connector card if you also want to end it — it opens this connector's removal dialog on the Billing page. A legacy website subscription reads Cancel Plan instead.

Troubleshooting

Symptom	Likely cause	What to do
Needs Attention appears right after saving	A value is wrong, the token scope was rejected, the subscription key is disabled, or neither family is available	Re-enter all three values from Security → APIs, confirm at least one API family, then choose Re-test
A tool returns a `403` while others succeed	Your credentials are not entitled to that tool's API family (Distributor vs Service Provider), or lack that scope	Ask Sherweb to grant the missing API family / scope for your API application
Authentication fails even though the Client ID and Secret look correct	The Subscription Key is missing or wrong	Re-enter the Subscription Key — it is required on every call in addition to the OAuth token
An amendment, cancellation, or order "hasn't happened yet"	The operation is asynchronous and still processing	Poll `sher_track_request` with the returned tracking id until it reads Success or Failure
A list response has no next-page cursor	Sherweb does not document pagination parameters for these endpoints	Treat the returned collection as that endpoint's response; narrow the customer/resource input where the tool supports it
Repeated calls return 429	Sherweb's API gateway or StackJack's aggregate tenant guard is throttling the burst	Reduce parallelism and retry after a short delay; do not automatically replay a write whose outcome is unknown
Write tools missing from your AI's tool list	Connector is on the Free tier, or the tools aren't selected for your client	Upgrade the Sherweb connector plan and check your tool selections on the MCP Setup page

Sherweb tools

sher_ · 21 tools · Free 17 · Pro 4

Billing

Tool	What it does
`sher_get_payable_charges` Free · Read-only	Get the Distributor billing 'payable charges' report — the charges YOU (the partner) owe Sherweb for a billing period.
`sher_get_receivable_charges` Free · Read-only	Get the Service Provider 'receivable charges' report for one customer — the charges YOU bill that customer for a billing period.

Customers

Tool	What it does
`sher_configure_customer_platforms` Pro · Write	Enable/configure one or more vendor platforms for a customer.
`sher_get_customer_platform_details` Free · Read-only	Get the details of one platform as configured for a customer.
`sher_get_customer_platform_meter_usages` Free · Read-only	Get metered (consumption-based) usage for one platform of a customer — e.g. usage-billed products under that platform.
`sher_get_customer_platforms_configurations` Free · Read-only	Get the platform configurations already enabled for a customer (which vendor platforms — e.g. Microsoft — are configured, and their parameter values).
`sher_list_customers` Free · Read-only	List all customers in your Sherweb Service Provider account.

Catalog & Platforms

Tool	What it does
`sher_get_customer_catalog` Free · Read-only	Get the full purchasable catalog for a customer — the SKUs available to order for them, with product metadata.
`sher_get_customer_catalog_items_pricing` Free · Read-only	Get pricing information for specific catalog SKUs for a customer.
`sher_get_platform_required_parameters` Free · Read-only	Get the parameters each platform requires when configuring it for a customer (identifiers and metadata).
`sher_get_platforms_for_skus` Free · Read-only	Resolve which platform each of a set of SKUs belongs to.
`sher_get_product_sku_mapping` Free · Read-only	Map vendor product identifiers to Sherweb SKUs for a platform (Microsoft only).
`sher_list_platforms` Free · Read-only	List all vendor platforms available in your Sherweb Service Provider account (e.g. Microsoft), each with its platformId (uuid).

Subscriptions

Tool	What it does
`sher_cancel_subscriptions` Pro · Destructive	Cancel one or more of a customer's subscriptions.
`sher_create_subscriptions_amendment` Pro · Destructive	Amend (change the quantity of) one or more of a customer's subscriptions.
`sher_get_customer_subscription_meters` Free · Read-only	Get the subscription meters for one customer on one platform — the metered/consumption counters underlying usage-based billing.
`sher_get_customer_subscriptions_details` Free · Read-only	Get the detailed subscription list for a customer — each subscription's id, product, quantity, term, and status.
`sher_get_customer_subscriptions_pricing_information` Free · Read-only	Get pricing information for a customer's subscriptions — per-subscription unit prices and fees.

Orders

Tool	What it does
`sher_place_order` Pro · Destructive	Place an order for a customer.
`sher_track_request` Free · Read-only	Track the status of an asynchronous Service Provider request by its trackingId — the requestTrackingId returned by sher_place_order, sher_create_subscriptions_amendment, or sher_cancel_subscriptions.
`sher_validate_place_order` Free · Read-only	Validate an order for a customer WITHOUT placing it — a dry-run that checks the cart against catalog/quantity/dependency rules and has no side effects.

Still need help? Ask the team