Pax8 Marketplace Integration

Connect your Pax8 partner account to give AI agents read-only access to customer companies, subscriptions, Azure usage, invoices, and the product catalog.

Overview

The Pax8 Marketplace Integration is purpose-built for MSPs managing cloud marketplace operations. It provides 5 read-only tools that allow AI agents to query your Pax8 companies, subscriptions, Azure usage data, billing invoices, and the product catalog.

The integration uses client credentials OAuth 2.0: you supply your Pax8 API credentials once during setup, and the system manages token acquisition and caching automatically. Credentials are encrypted at rest. Bearer tokens are cached with automatic refresh. Once connected, a "Pax8" tool group is automatically created and ready to assign to any agent.

info

All 5 Pax8 tools are strictly read-only. Agents cannot provision subscriptions, update companies, place orders, or make any changes through this integration.

Use Cases

Renewal Planning - Agent queries customer subscriptions by billing term and commitment end date to identify upcoming renewals
Azure Cost Review - AICOS retrieves Azure usage summaries across customer tenants to prepare cost optimization recommendations
Invoice Reconciliation - Agent looks up invoice line items for a specific customer to verify billing accuracy
Customer Onboarding Research - Agent retrieves company details and active subscriptions for a new customer during an account review
Product Pricing Lookup - Agent checks the Pax8 product catalog for current pricing on a product a customer is asking about
License Status Check - Agent queries subscription status for a customer to answer a licensing question in a support ticket

How It Works

IT Admin enters              Token acquired               Agents query Pax8
Pax8 credentials             via client credentials       using tool group
       |                             |                           |
       v                             v                           v
+--------------+          +-------------------+        +------------------+
| Pax8 Client  |          | OAuth2 client     |        | Search companies,|
| ID and       |  --->    | credentials flow, |  --->  | subscriptions,   |
| Client Secret|          | 24-hour token     |        | Azure usage,     |
|              |          | auto-refreshed    |        | invoices, catalog|
+--------------+          +-------------------+        +------------------+

Pax8 tokens are valid for 24 hours. The system automatically refreshes tokens before they expire, using in-process and database-level locking to prevent concurrent refresh races.

Getting Started

Prerequisites

Before connecting Pax8:

Pro Plus+ Subscription - The Pax8 integration requires the custom.pax8 feature code on your subscription
Pax8 Partner Account - Your organization must be an active Pax8 partner
Pax8 API Credentials - You need a client ID and client secret from Pax8 (see Pax8 documentation on enabling API access in your partner portal)
Control Bridge Admin Access - You must be a Control Bridge administrator to configure the integration

Step 1: Enter Pax8 Credentials

Navigate to Build > Connections > Pax8
Enter your Pax8 Client ID
Enter your Pax8 Client Secret
Click Save Connection

Credentials are encrypted at rest immediately upon saving.

Step 2: Test the Connection

After saving, click Test Connection
The system attempts to acquire an access token using your client credentials
Confirm you see a success message indicating the connection is active

If the test fails, verify your credentials are correct and that your Pax8 account has API access enabled.

Step 3: Assign the Pax8 Tool Group to Agents

Pax8 tools are bundled into a "Pax8" tool group automatically created at connection time:

Navigate to Build > AI Agents > Agents
Edit the agent that should have Pax8 access
Go to the Tools tab
In the Tool Groups section, enable the Pax8 group
Save the agent

All 5 Pax8 tools are assigned together as a single unit via the tool group.

Available Tools

When Pax8 is connected, 5 read-only tools are created and grouped under the "Pax8" tool group.

1. Pax8 Search Companies (`pax8_search_companies`)

Search and retrieve customer companies and their contacts from your Pax8 partner account.

Parameter	Type	Required	Description
action	string	Yes	`list`, `get`, or `contacts`
companyId	string (UUID)	Conditional	Pax8 company UUID (required for `get` and `contacts`)
filters	object	No	Filters for `list` action (see below)
page	number	No	Page number, 0-indexed (default: 0)
size	number	No	Results per page (max: 200, default: 50)

Available filters for list:

Filter	Description
`city`	Filter by city
`country`	Filter by country code
`stateOrProvince`	Filter by state or province
`postalCode`	Filter by postal code
`status`	`Active`, `Inactive`, or `Deleted`

info

The Pax8 API does not support server-side company name search. To find a company by name, use the list action to retrieve companies and scan the results. Use location or status filters to narrow down large customer lists.

Action summary:

Action	Description
`list`	List and filter companies with pagination
`get`	Get full details for a specific company
`contacts`	List contacts for a specific company (Admin, Billing, Technical)

Key company fields:

Field	Description
`id`	Pax8 company UUID
`name`	Company name
`status`	`Active`, `Inactive`, or `Deleted`
`externalId`	Microsoft Tenant ID (for Microsoft customers)
`address`	Street, city, state, postal code, country

2. Pax8 Search Subscriptions (`pax8_search_subscriptions`)

Search and inspect subscriptions, addon relationships, commitment terms, and subscription history.

Parameter	Type	Required	Description
action	string	Yes	`list`, `get`, or `history`
subscriptionId	string (UUID)	Conditional	Pax8 subscription UUID (required for `get` and `history`)
filters	object	No	Filters for `list` action (see below)
sort	string	No	Sort field and direction (e.g., `startDate,DESC`)
page	number	No	Page number, 0-indexed (default: 0)
size	number	No	Results per page (max: 200, default: 50)

Available filters for list:

Filter	Description
`companyId`	Filter by Pax8 company ID
`productId`	Filter by Pax8 product ID
`status`	Subscription status (see Status Values below)
`billingTerm`	`Monthly`, `Annual`, `2-Year`, `3-Year`, `One-Time`, `Trial`, `Activation`

Allowed sort fields: startDate, endDate, createdDate, updatedDate, quantity, price

Action summary:

Action	Description
`list`	Search and filter subscriptions across all companies
`get`	Get full subscription details including commitment term and coterminosity date
`history`	View change history for a subscription

Subscription status values:

Status	Description
`Active`	Fully operational subscription
`Cancelled`	Subscription terminated
`Trial`	Time-limited trial
`Converted`	Trial transitioned to paid
`PendingManual`	Awaiting manual provisioning
`PendingAutomated`	Awaiting automated provisioning
`PendingCancel`	Cancellation scheduled

tip

Use get action to retrieve commitmentTerm.endDate for a subscription - this is the coterminosity date indicating when the commitment term ends. Subscriptions with a non-null parentSubscriptionId are addons to another subscription.

3. Pax8 Azure Intelligence (`pax8_azure_intelligence`)

Azure-specific queries for plans, usage summaries, and granular usage line items.

Parameter	Type	Required	Description
action	string	Yes	`find_azure_subscriptions`, `usage_summaries`, `usage_lines`, or `usage_summary_detail`
companyId	string	For `find_azure_subscriptions`	Pax8 company ID
subscriptionId	string	For `usage_summaries`	Pax8 subscription ID
usageSummaryId	string	Conditional	Usage summary ID (required for `usage_lines`, `usage_summary_detail`)
usageDate	string	For `usage_lines`	Date for usage lines (yyyy-MM-dd)
filters	object	No	Optional `resourceGroup` or `productId` filters
page	number	No	Page number, 0-indexed (default: 0)
size	number	No	Results per page (max: 200, default: 50)

Recommended workflow for Azure usage:

Step 1: find_azure_subscriptions (with companyId)
        -> Returns Azure Plan subscription IDs for the company

Step 2: usage_summaries (with subscriptionId from Step 1)
        -> Returns current month usage summaries by resource group

Step 3: usage_lines (with usageSummaryId from Step 2 + usageDate)
        -> Returns granular line items for a specific day

Action summary:

Action	Description
`find_azure_subscriptions`	Find Azure Plan subscriptions for a company
`usage_summaries`	Get current month usage summaries (by resource group)
`usage_summary_detail`	Get details for a specific usage summary
`usage_lines`	Get granular usage line items for a specific date

info

Azure usage data (usage_summaries) reflects the current calendar month only. For historical usage, use the pax8_search_invoices tool to retrieve invoice line items from past billing periods.

4. Pax8 Search Invoices (`pax8_search_invoices`)

Search invoices and retrieve billing details including line items and draft upcoming charges.

Parameter	Type	Required	Description
action	string	Yes	`list`, `get`, `items`, or `draft_items`
invoiceId	string (UUID)	Conditional	Pax8 invoice UUID (required for `get` and `items`)
filters	object	No	Filters for `list`, `items`, and `draft_items` (see below)
sort	string	No	Sort field and direction (e.g., `invoiceDate,DESC`)
page	number	No	Page number, 0-indexed (default: 0)
size	number	No	Results per page (max: 200, default: 50)

Available filters:

Filter	Action	Description
`status`	`list`	`Unpaid`, `Paid`, `Void`, `Carried`, `Nothing Due`, `Credited`
`invoiceDateFrom`	`list`	Start date filter (yyyy-MM-dd)
`invoiceDateTo`	`list`	End date filter (yyyy-MM-dd)
`companyId`	`items`, `draft_items`	Filter line items by company
`monthOffset`	`draft_items`	`0` for current month, `1` for next month

Allowed sort fields: invoiceDate, dueDate, total, balance

Action summary:

Action	Description
`list`	Search invoices by status, date range, and other filters
`get`	Get full details for a specific invoice
`items`	Get line items for an invoice (supports company filter)
`draft_items`	Get upcoming charges before the billing cycle closes

info

Pax8 invoices are generated on the 4th of each month. Use draft_items with monthOffset: 0 to see upcoming charges before invoices are finalized. Once approved, invoices are immutable.

5. Pax8 Search Products (`pax8_search_products`)

Search the Pax8 product catalog for pricing, product details, and dependency requirements.

Parameter	Type	Required	Description
action	string	Yes	`list`, `get`, `pricing`, or `dependencies`
productId	string (UUID)	Conditional	Pax8 product UUID (required for `get`, `pricing`, `dependencies`)
search	string	No	Search query for `list` (searches name, vendor, and SKU)
filters	object	No	`vendorName` filter for `list`
companyId	string	No	For `pricing` - returns company-specific rates
sort	string	No	Sort field and direction (e.g., `name,ASC`)
page	number	No	Page number, 0-indexed (default: 0)
size	number	No	Results per page (max: 200, default: 50)

Allowed sort fields: name, vendorName

Action summary:

Action	Description
`list`	Search products by name, vendor, or SKU
`get`	Get full product details including description and commitment requirements
`pricing`	Get pricing rates including partner buy rates and suggested retail prices
`dependencies`	Get product dependencies and commitment requirements

Pricing type values: Flat, Volume, Tiered, Mark-Up

tip

To look up pricing for a specific product, first use list with a search query to find the product and get its ID, then use pricing with that product ID. Optionally provide a companyId to get company-specific rates.

Security & Limitations

Security

Client credentials OAuth 2.0 - Uses the industry-standard client credentials flow for secure authentication
AES-256-CBC encryption - Client secret is encrypted at rest using your tenant's encryption key
Two-level token refresh locking - In-process mutex plus database-level optimistic locking prevents token replay attacks on 401 responses
Read-only access - All API calls are GET requests only; no write operations are possible
Sort field validation - Sort parameters are validated against per-tool allowlists before being sent to the API; invalid values are silently ignored
Tenant isolation - Credentials and tools are strictly scoped to your tenant
Audit logging - Every tool execution is logged with the agent, action, and result

Rate Limits

Pax8 enforces a rate limit of 1000 calls per minute. The integration tracks calls per process instance and introduces delays if the limit is approaching. On HTTP 429 responses, the integration retries with exponential backoff (maximum 3 retries, capped at 60 seconds).

Limitations

Read-only - Cannot provision, cancel, or modify subscriptions, companies, or orders
Single connection - Only one Pax8 connection per Control Bridge tenant
No name search for companies - Pax8's company API does not support server-side name filtering; use location or status filters to narrow results
Current month usage only - Azure usage summaries reflect the current calendar month; historical usage requires invoice line items
Pagination required - Large result sets require cursor-based pagination; not all results are returned in a single call
No product availability - Cannot check real-time product availability or provisioning status

Troubleshooting

Connection Test Fails

Problem: The test connection returns an error after entering credentials

Solutions:

Verify your Pax8 client ID and client secret are correct
Confirm your Pax8 account has API access enabled (contact Pax8 partner support if unsure)
Ensure the API application credentials have not been rotated or revoked in the Pax8 portal
Check for extra spaces in the credential fields

Agent Cannot Find Pax8 Tools

Problem: Pax8 tools do not appear when editing an agent

Solutions:

Verify the Pax8 connection is active at Build > Connections > Pax8
Check that the "Pax8" tool group exists at Build > AI Agents > Tool Groups
Assign the Pax8 tool group (not individual tools) to the agent
Refresh the page and try again

Company Search Returns Too Many Results

Problem: pax8_search_companies with list returns many companies with no easy way to filter by name

Solutions:

Use location filters (city, country, stateOrProvince) to narrow results
Use the status filter to limit to Active companies
Use pagination to browse through results and identify the target company
Once you find the company ID, save it in agent memory or knowledge for future use

Azure Usage Returns Empty

Problem: pax8_azure_intelligence with usage_summaries returns no data

Solutions:

Verify the subscription ID is an Azure Plan subscription - use find_azure_subscriptions first to get valid Azure subscription IDs
Confirm the company has active Azure usage in the current month
Check that the correct companyId is being used with find_azure_subscriptions

Token Errors During Execution

Problem: Agent executions fail with authentication errors

Solutions:

Navigate to Build > Connections > Pax8 and click Test Connection
If the test fails, your client credentials may have been rotated in Pax8 - update them
After updating credentials, the system will acquire a fresh token on the next execution

Best Practices

Agent Instructions

Help your agents use Pax8 tools effectively:

When working with Pax8 data:
1. For company lookup, use pax8_search_companies with filters (city, country,
   or status) rather than browsing all companies - name search is not available
2. For subscription searches, always include companyId filter when you know the
   company to avoid returning subscriptions across all customers
3. For Azure usage analysis, follow the three-step workflow: find_azure_subscriptions
   -> usage_summaries -> usage_lines for granular detail
4. For upcoming billing, use pax8_search_invoices with draft_items action rather
   than waiting for the monthly invoice to be finalized

Configuration

Assign the Pax8 tool group to agents that handle customer account management, billing, or subscription inquiries
Consider creating a dedicated MSP operations agent with Pax8 access for marketplace-related tasks
Test your agents with common Pax8 queries (customer subscription list, upcoming invoice) after setup

Security

Use a dedicated API application in Pax8 for Control Bridge, separate from any human user credentials
If you rotate API credentials in Pax8, update them in Control Bridge promptly to avoid execution failures
Review agent execution logs periodically to monitor what Pax8 data agents are accessing

Tools Overview - All available agent tools
Agents - Configure agents to use tools
Agent Executions - View tool execution logs
Crayon Cloud IQ Integration - Cloud license management integration for CSP resellers
NinjaOne RMM Integration - IT infrastructure monitoring for MSPs

Overview​

Use Cases​

How It Works​

Getting Started​

Prerequisites​

Step 1: Enter Pax8 Credentials​

Step 2: Test the Connection​

Step 3: Assign the Pax8 Tool Group to Agents​

Available Tools​

1. Pax8 Search Companies (pax8_search_companies)​

2. Pax8 Search Subscriptions (pax8_search_subscriptions)​

3. Pax8 Azure Intelligence (pax8_azure_intelligence)​

4. Pax8 Search Invoices (pax8_search_invoices)​

5. Pax8 Search Products (pax8_search_products)​

Security & Limitations​

Security​

Rate Limits​

Limitations​

Troubleshooting​

Connection Test Fails​

Agent Cannot Find Pax8 Tools​

Company Search Returns Too Many Results​

Azure Usage Returns Empty​

Token Errors During Execution​

Best Practices​

Agent Instructions​

Configuration​

Security​

Related Topics​

Overview

Use Cases

How It Works

Getting Started

Prerequisites

Step 1: Enter Pax8 Credentials

Step 2: Test the Connection

Step 3: Assign the Pax8 Tool Group to Agents

Available Tools

1. Pax8 Search Companies (`pax8_search_companies`)

2. Pax8 Search Subscriptions (`pax8_search_subscriptions`)

3. Pax8 Azure Intelligence (`pax8_azure_intelligence`)

4. Pax8 Search Invoices (`pax8_search_invoices`)

5. Pax8 Search Products (`pax8_search_products`)

Security & Limitations

Security

Rate Limits

Limitations

Troubleshooting

Connection Test Fails

Agent Cannot Find Pax8 Tools

Company Search Returns Too Many Results

Azure Usage Returns Empty

Token Errors During Execution

Best Practices

Agent Instructions

Configuration

Security

Related Topics