Sherweb API Patterns & MCP Tools

Overview

The Sherweb Partner API provides programmatic access to distributor-level operations including customer management, subscription lifecycle, and billing data. The API uses OAuth 2.0 client credentials flow for authentication, requires a subscription key header for API management, and exposes two main scopes: distributor and service-provider. This skill covers authentication, endpoints, MCP tool usage, error handling, and best practices.

Authentication

OAuth 2.0 Client Credentials Flow

Sherweb uses the OAuth 2.0 client credentials grant for machine-to-machine authentication. No user interaction is required.

Token Endpoint:

POST https://api.sherweb.com/auth/oidc/connect/token

Request Parameters:

Token Response:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6...",
  "expires_in": 3600,
  "token_type": "Bearer"
}

Key details:

• Tokens expire after 1 hour (3600 seconds)
• Cache the token and reuse it until near expiry
• Request a new token 5 minutes before expiry to avoid gaps
• The token is sent as a Bearer token in the Authorization header

Subscription Key

In addition to the Bearer token, every API request must include the API management subscription key:

This key is obtained from the Sherweb Partner Portal (cumulus.sherweb.com) under Security > APIs.

Required Headers

Every API request must include:

Environment Variables

export SHERWEB_CLIENT_ID="your-client-id"
export SHERWEB_CLIENT_SECRET="your-client-secret"
export SHERWEB_SUBSCRIPTION_KEY="your-subscription-key"
export SHERWEB_MCP_URL="https://your-sherweb-mcp-url"

Obtaining Credentials

1. Log into the Sherweb Partner Portal at cumulus.sherweb.com
2. Navigate to Security > APIs
3. Create a new API application or manage existing credentials
4. Note your Client ID, Client Secret, and Subscription Key
5. Store these securely -- the Client Secret is shown only once

Scopes

Sherweb supports two API scopes that control the level of access:

Scope Selection

• Most MSPs use service-provider scope - This gives access to your own customers and subscriptions
• Distributor scope is for organizations that manage multiple service providers (e.g., master agents, holding companies)
• The scope is specified when requesting the OAuth token, not per-request

API Endpoints

Base URLs

Key Endpoints

MCP Tool Reference

Customer Tools

Subscription Tools

Billing Tools

Pagination

Page-Based Pagination

All list endpoints use 1-based page pagination:

Pagination Response Metadata:

Iterating Through All Pages

1. Call the endpoint with page=1 and pageSize=100
2. Check totalPages in the response
3. If more pages exist, increment page and call again
4. Continue until page >= totalPages
5. Collect results from each response

Accept-Language Support

The Sherweb API supports localized responses via the Accept-Language header:

This is particularly useful since Sherweb is a Canadian company with bilingual support. Product names, descriptions, and error messages can be returned in either language.

Token Caching

Token Lifecycle

Request Token --> Cache Token --> Use Token (up to 1 hour) --> Refresh Token
                                        |
                              Refresh 5 min before expiry

Caching strategy:

1. Request a token on first API call
2. Store the token and its expiry time (current_time + expires_in)
3. Reuse the cached token for all subsequent requests
4. When the token is within 5 minutes of expiry, request a new one
5. Never request a new token for every API call -- this wastes quota and adds latency

Rate Limits

Rate Limit Details

When rate limited, the API returns a 429 Too Many Requests response with:

Rate limit strategy:

1. Implement exponential backoff on 429 responses
2. Respect the Retry-After header when present
3. Batch related operations to reduce total API calls
4. Use maximum pageSize=100 to minimize pagination requests

Error Handling

HTTP Status Codes

| C