Sherweb API Patterns

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:

| Parameter | Value | |-----------|-------| | grant_type | client_credentials | | client_id | Your Sherweb Client ID | | client_secret | Your Sherweb Client Secret | | scope | distributor or service-provider (see Scopes section) |

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:

| Header | Value | Description | |--------|-------|-------------| | Ocp-Apim-Subscription-Key | Your subscription key | API management gateway key |

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

Required Headers

Every API request must include:

| Header | Value | |--------|-------| | Authorization | Bearer <access_token> | | Ocp-Apim-Subscription-Key | <subscription_key> | | Content-Type | application/json | | Accept | application/json |

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 | Description | Base URL | |-------|-------------|----------| | distributor | Full distributor-level access to all service providers and their customers | https://api.sherweb.com/distributor/v1 | | service-provider | Scoped to a single service provider (MSP) and their customers | https://api.sherweb.com/service-provider/v1 |

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

| Scope | Base URL | |-------|----------| | Distributor | https://api.sherweb.com/distributor/v1 | | Service Provider | https://api.sherweb.com/service-provider/v1 |

Key Endpoints

| Endpoint | Method | Description | |----------|--------|-------------| | /customers | GET | List customers | | /customers/{id} | GET | Get customer details | | /customers/{id}/accounts-receivable | GET | Customer AR data | | /subscriptions | GET | List subscriptions | | /subscriptions/{id} | GET | Get subscription details | | /subscriptions/{id}/quantity | PATCH | Change subscription quantity | | /billing/periods | GET | List billing periods | | /billing/periods/{id}/charges | GET | Get payable charges | | /billing/invoices | GET | List invoices | | /billing/invoices/{id} | GET | Get invoice details |

MCP Tool Reference

Customer Tools

| Tool | Description | Parameters | |------|-------------|------------| | sherweb_customers_list | List and search customers | page, pageSize, search | | sherweb_customers_get | Get a single customer | customerId (required) | | sherweb_customers_get_accounts_receivable | Get customer AR data | customerId (required) |

Subscription Tools

| Tool | Description | Parameters | |------|-------------|------------| | sherweb_subscriptions_list | List subscriptions with filters | customerId, page, pageSize, status | | sherweb_subscriptions_get | Get a single subscription | subscriptionId (required) | | sherweb_subscriptions_change_quantity | Modify seat count | subscriptionId (required), quantity (required) |

Billing Tools

| Tool | Description | Parameters | |------|-------------|------------| | sherweb_billing_get_billing_periods | List billing periods | page, pageSize | | sherweb_billing_get_payable_charges | Get charges for a period | billingPeriodId (required), page, pageSize | | sherweb_billing_get_charge_details | Get charge breakdown | chargeId (required) | | sherweb_billing_get_invoices | List invoices | page, pageSize, status | | sherweb_billing_get_invoice_details | Get invoice details | invoiceId (required) |

Pagination

Page-Based Pagination

All list endpoints use 1-based page pagination:

| Parameter | Description | Default | Max | |-----------|-------------|---------|-----| | page | Page number (1-based) | 1 | - | | pageSize | Results per page | 25 | 100 |

Pagination Response Metadata:

| Field | Description | |-------|-------------| | page | Current page number | | pageSize | Number of results per page | | totalCount | Total number of records | | totalPages | Total number of pages |

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:

| Header | Values | Description | |--------|--------|-------------| | Accept-Language | en, fr | Response language (English or French) |

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

| Metric | Limit | |--------|-------| | Requests per second | Varies by endpoint | | Requests per minute | Varies by subscription tier |

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

| Header | Description | |--------|-------------| | Retry-After | Seconds to wait before retrying |

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