Crayon Cloud IQ Integration
Connect your Crayon Cloud IQ platform to give AI agents read-only access to cloud license management data, including organizations, subscriptions, Azure usage, and billing.
Overview
The Crayon Cloud IQ Integration is purpose-built for Microsoft CSP resellers managing customer tenants. It provides 4 focused read-only tools that allow AI agents to query your Crayon organizations, customer subscriptions, Azure plans and usage, and billing invoices.
Unlike OAuth-based integrations, Crayon uses an OAuth2 password grant flow: you supply your Crayon API credentials once during setup, and the system manages token acquisition and caching automatically. Credentials are stored encrypted using AES-256-CBC. Bearer tokens are cached in the database with a 5-minute pre-expiry buffer, and distributed locking prevents token replay attacks.
All 4 Crayon tools are strictly read-only. Agents cannot create, update, or delete subscriptions, customers, or billing records through this integration.
Use Cases
- Subscription Status Lookup - Agent queries subscription status for a customer tenant before responding to a licensing question
- Azure Cost Analysis - AICOS retrieves Azure usage data for a customer tenant to prepare cost optimization recommendations
- Billing Reconciliation - Agent looks up invoice details for a specific customer to verify billing accuracy
- Partner Account Review - Agent retrieves organization and customer details for a quarterly partner account review
- Renewal Planning - Agent checks coterminosity dates across subscriptions to identify upcoming renewals for a customer
- License Agreement Lookup - Agent retrieves active agreements for a customer to answer compliance questions
How It Works
IT Admin enters Credentials stored Agents query Crayon
API credentials encrypted, token cached using tool group
| | |
v v v
+--------------+ +-------------------+ +------------------+
| Crayon API | | OAuth2 password | | Search orgs, |
| client ID, | ---> | grant, bearer | ---> | subscriptions, |
| secret, | | token cached with | | Azure data, |
| username, | | distributed lock | | billing invoices |
| password | +-------------------+ +------------------+
+--------------+
The system acquires a bearer token using your credentials and caches it in the database. When the token nears expiry (within 5 minutes), it refreshes automatically. Distributed locking ensures only one instance refreshes the token at a time, preventing replay attacks.
Getting Started
Prerequisites
Before connecting Crayon Cloud IQ:
- Pro Plus+ Subscription - The Crayon integration requires the
custom.crayonfeature code on your subscription - Crayon Account - Your organization must be a registered Crayon partner with API access enabled
- Crayon API Credentials - You need your Crayon client ID, client secret, username, and password (obtained from your Crayon account manager or the Crayon partner portal)
- Control Bridge Admin Access - You must be a Control Bridge administrator to configure the integration
MFA must be disabled on the Crayon API user account. OAuth ROPC (password grant) cannot complete MFA challenges; if MFA is enabled, the integration will fail to refresh tokens after the first ~5 hours and the connection will appear to work, then suddenly stop. Use a dedicated API user account without MFA enabled.
Step 1: Enter Crayon Credentials
- Navigate to Build > Connections > Crayon
- Enter your Crayon Client ID
- Enter your Crayon Client Secret
- Enter your Crayon Username (the email address used to log in to Crayon)
- Enter your Crayon Password
- Click Save Connection
Credentials are encrypted at rest immediately upon saving.
Do not share your Crayon credentials with anyone. These credentials provide access to your entire Crayon partner account, including all customer tenants and billing data. Store them securely.
Step 2: Test the Connection
- After saving, click Test Connection
- The system attempts to acquire a bearer token using your credentials
- Confirm you see a success message indicating the connection is active
If the test fails, verify your credentials are correct and that your Crayon account has API access enabled.
Step 3: Assign the Crayon Tool Group to Agents
Crayon tools are bundled into a "Crayon" tool group automatically created at connection time:
- Navigate to Build > AI Agents > Agents
- Edit the agent that should have Crayon access
- Go to the Tools tab
- In the Tool Groups section, enable the Crayon group
- Save the agent
All 4 Crayon tools are assigned together as a single unit via the tool group.
Available Tools
When Crayon is connected, 4 read-only tools are created and grouped under the "Crayon" tool group.
1. Crayon Search Organizations (crayon_search_organizations)
Query organizations and customer tenants in your Crayon partner account.
| Parameter | Type | Required | Description |
|---|---|---|---|
| action | string | Yes | list_organizations, get_organization, list_customers, get_customer, or get_customer_detailed |
| organizationId | integer | Conditional | Organization ID (required for get_organization, list_customers) |
| customerTenantId | integer | Conditional | Customer tenant ID (required for get_customer, get_customer_detailed) |
| search | string | No | Search by name |
| page | integer | No | Page number (starts at 1, default: 1) |
| pageSize | integer | No | Results per page (default: 25) |
Action summary:
| Action | Description |
|---|---|
list_organizations | List all organizations in your Crayon account |
get_organization | Get detailed info for a specific organization |
list_customers | List customer tenants under an organization |
get_customer | Get details for a specific customer tenant |
get_customer_detailed | Get full customer details including profile, address, and contact info |
For security, the get_customer_detailed action automatically redacts the customer's admin password before returning data to the agent. Only the username is returned.
2. Crayon Search Subscriptions (crayon_search_subscriptions)
Query subscriptions, addon offers, coterminosity dates, and agreements.
| Parameter | Type | Required | Description |
|---|---|---|---|
| action | string | Yes | list_subscriptions, get_subscription, list_addon_offers, get_coterminosity, or list_agreements |
| organizationId | integer | Conditional | Organization ID (for list_subscriptions, get_coterminosity, list_agreements) |
| customerTenantId | integer | Conditional | Customer tenant ID (for list_subscriptions, get_coterminosity) |
| subscriptionId | integer | Conditional | Subscription ID (for get_subscription, list_addon_offers, get_coterminosity) |
| termDuration | string | Conditional | ISO 8601 duration for coterminosity: P1M, P1Y, P3Y |
| status | string | No | Filter: active, suspended, deleted, or expired |
| search | string | No | Search by subscription name, ID, or product names |
| page | integer | No | Page number (default: 1) |
| pageSize | integer | No | Results per page (default: 25) |
Action summary:
| Action | Description |
|---|---|
list_subscriptions | Search subscriptions across organizations and customer tenants |
get_subscription | Get full details for a specific subscription |
list_addon_offers | List available addon offers for a subscription |
get_coterminosity | Get coterminosity dates for aligning subscription renewals |
list_agreements | List Microsoft Customer Agreements and other program agreements |
3. Crayon Azure Intelligence (crayon_azure_intelligence)
Query Azure plans, Azure subscriptions, and monthly usage data for customer tenants.
| Parameter | Type | Required | Description |
|---|---|---|---|
| action | string | Yes | get_customer_azure_plan, get_azure_plan, list_azure_subscriptions, get_azure_subscription, or get_azure_usage |
| customerTenantId | integer | For get_customer_azure_plan | Customer tenant ID |
| azurePlanId | integer | Conditional | Azure plan ID (required for several actions) |
| azureSubscriptionId | integer | For get_azure_subscription | Crayon integer Azure subscription ID (the Id field from list_azure_subscriptions) |
| azureSubscriptionGuid | string | For get_azure_usage | Azure Subscription GUID (the SubscriptionId field from list_azure_subscriptions) |
| year | integer | For get_azure_usage | Year for usage data |
| month | integer | For get_azure_usage | Month for usage data |
| search | string | No | Search filter for list_azure_subscriptions |
| page | integer | No | Page number (default: 1) |
| pageSize | integer | No | Results per page (default: 25) |
Action summary:
| Action | Description |
|---|---|
get_customer_azure_plan | Get the Azure Plan for a customer tenant |
get_azure_plan | Get details for a specific Azure plan |
list_azure_subscriptions | List Azure subscriptions under an Azure plan |
get_azure_subscription | Get details for a specific Azure subscription |
get_azure_usage | Get monthly Azure usage data for a subscription |
Azure usage data is returned as a summarized view showing total cost, top services by cost, and billing period. The raw usage CSV is downloaded, parsed, and summarized automatically so agents receive readable data rather than a raw file reference.
4. Crayon Search Billing (crayon_search_billing)
Query invoices, billing statements, and invoice profiles.
| Parameter | Type | Required | Description |
|---|---|---|---|
| action | string | Yes | list_invoices, list_billing_statements, list_invoice_profiles, or get_invoice_profile |
| organizationId | integer | Conditional | Organization ID (required for list_invoices, optional for others) |
| invoiceProfileId | integer | Conditional | Invoice profile ID (for get_invoice_profile, filter for list_billing_statements) |
| from | string | No | Start date filter ISO 8601 (for list_billing_statements) |
| to | string | No | End date filter ISO 8601 (for list_billing_statements) |
| page | integer | No | Page number (default: 1) |
| pageSize | integer | No | Results per page (default: 25) |
Action summary:
| Action | Description |
|---|---|
list_invoices | List invoices for an organization |
list_billing_statements | List billing statements with optional date range filtering |
list_invoice_profiles | List invoice profiles (billing entities) |
get_invoice_profile | Get details for a specific invoice profile |
Security & Limitations
Security
- AES-256-CBC encryption - API credentials are encrypted at rest using your tenant's encryption key
- Cached token security - Bearer tokens are cached in the database with distributed locking using the ErrorMessage sentinel pattern, preventing token replay attacks
- Automatic token refresh - Tokens are refreshed automatically 5 minutes before expiry
- Read-only access - All API calls are GET requests only; no write operations are possible
- Tenant isolation - Credentials and tools are strictly scoped to your tenant
- Credential redaction - Customer admin passwords are redacted before any data is returned to agents
- Audit logging - Every tool execution is logged with the agent, action, and result
Limitations
- Read-only - Cannot create, update, or delete any Crayon records
- Single connection - Only one Crayon connection per Control Bridge tenant
- Azure usage summary only - Azure usage data is summarized; raw CSV files are not returned to agents
- Organization scoping - Agents can only access data within organizations your Crayon credentials are authorized for
- Rate limits - Crayon does not publish specific rate limits; the integration retries with exponential backoff on 429 responses
Troubleshooting
Connection Test Fails
Problem: The test connection returns an error after entering credentials
Solutions:
- Verify your Crayon client ID, client secret, username, and password are correct
- Confirm your Crayon account has API access enabled (contact your Crayon account manager if unsure)
- Check that your Crayon credentials have not expired or been reset
- Ensure there are no extra spaces in the credential fields
Agent Returns "Crayon Connection Is Inactive"
Problem: Agent execution returns a connection status error
Solutions:
- Navigate to Build > Connections > Crayon and check the connection status
- Click Test Connection - if it fails, update your credentials if they have changed
- After fixing, clear the tool cache and retry the agent execution
Agent Cannot Find Crayon Tools
Problem: Crayon tools do not appear when editing an agent
Solutions:
- Verify the Crayon connection is active at Build > Connections > Crayon
- Check that the "Crayon" tool group exists at Build > AI Agents > Tool Groups
- Assign the Crayon tool group (not individual tools) to the agent
- Refresh the page and try again
Azure Usage Returns No Data
Problem: crayon_azure_intelligence with get_azure_usage returns no data
Solutions:
- Verify the correct
azurePlanIdandazureSubscriptionGuidare being used - uselist_azure_subscriptionsfirst to find valid Azure subscription GUIDs (theSubscriptionIdfield, not the integerId) - Confirm the year and month have available usage data (current month may have incomplete data until the billing cycle closes)
- Check that the Azure subscription has actual usage for the specified period
Token Errors in Executions
Problem: Executions fail with authentication errors despite a valid connection
Solutions:
- Navigate to Build > Connections > Crayon and click Test Connection
- If the test fails, your Crayon password may have been reset - update the credentials
- Check whether MFA was enabled on the Crayon API user account. OAuth ROPC cannot complete MFA challenges; tokens will refresh successfully for the first ~5 hours from cache, then start failing. Disable MFA on the API user account or switch to a dedicated API user without MFA.
- The system will automatically acquire a fresh token after credentials are updated
Best Practices
Agent Instructions
Help your agents use Crayon tools effectively:
When working with Crayon Cloud IQ data:
1. Start with crayon_search_organizations to find the organization or customer
tenant before querying subscriptions or billing
2. For subscription searches, use customerTenantId to scope results to a
specific customer rather than querying all subscriptions
3. For Azure usage, first use get_customer_azure_plan to find the Azure plan,
then list_azure_subscriptions to find specific subscriptions, then
get_azure_usage for the monthly data
4. When looking up billing, use list_invoices with the organization ID to
scope results to the correct billing entity
Configuration
- Assign the Crayon tool group only to agents that handle cloud licensing or billing inquiries
- Consider creating a dedicated MSP operations agent with the Crayon tool group rather than adding it to general-purpose agents
- Test with common customer queries after setup to verify agents interpret data correctly
Security
- Rotate your Crayon API credentials periodically and update them in Control Bridge promptly
- If the employee who set up the Crayon connection leaves, update the credentials to use a service account
- Review agent execution logs regularly to monitor what Crayon data is being queried
Related Topics
- Tools Overview - All available agent tools
- Agents - Configure agents to use tools
- Agent Executions - View tool execution logs
- Pax8 Marketplace Integration - Alternative marketplace integration for Pax8 MSPs