Connect Crayon

Crayon is a global software and cloud distributor, and its partner platform, Cloud-iQ, is where a partner buys and manages Microsoft CSP (including the New Commerce licences), Azure Plans, AWS, Google and Adobe subscriptions for its end customers and reads the bills that follow. Crayon is now part of SoftwareOne, but its API is still Crayon-branded end to end, so this connector is too. StackJack talks to your Cloud-iQ partner tenant, and one connection reaches every customer that tenant manages.

Connecting Crayon to StackJack gives your AI assistant a family of crayon_ MCP tools. MCP (Model Context Protocol) tools are the standardized commands an AI assistant can call through StackJack. With them, your AI can:

• Answer "what does this customer have and what does it cost": list your organizations and customer tenants, then every subscription with its quantity, status, renewal date and unit price, filtered by customer, publisher or status
• See what can change and when: the upgrade targets a subscription is eligible for, the terms and billing cycles it can switch to, the add-ons on offer, the conversion options and the coterminosity dates that line a new seat up with an existing end date
• Reconcile the month: billing statements, grouped statements, invoices, invoice profiles, groupings, usage cost by organization, subscription, category, sub category or resource group, and the NCE license-based export
• Pull the files Crayon produces: billing statement workbooks, reconciliation CSVs, the billing records file, generated exports and the product price-list workbook, each handed back as a download link
• Check Azure: the Azure Plan behind a customer tenant, its Azure subscriptions, and a month of usage for any of them
• Browse the catalog: the products you can buy under your agreements (by part number, publisher, program and billing cycle), agreements, programs, publishers and regions
• Review access and activity: Cloud-iQ users, which organizations each can reach, the activity log, and the API user's own profile
• Buy and change (on Pro plans): verify and check out an order, create a Microsoft NCE subscription, change seats, status and renewals, add add-ons, upgrade or convert a subscription, create, rename and cancel Azure subscriptions, set reseller prices, and manage customer tenants, users, invoice profiles, groupings and carts

How StackJack authenticates to Crayon

Crayon signs a partner integration in with two things at once, and StackJack needs all four values:

• An API client: a Client ID and a Client Secret, created in Cloud-iQ under Clients.
• A Cloud-iQ API user: a user name and a password, created in Cloud-iQ under Users.

StackJack exchanges the four values for a short-lived access token and renews it by itself, so there is nothing to refresh and no expiry to track. The API user decides what StackJack can see and do: its Cloud-iQ role and the organizations it has been given access to are the limits, and Crayon has no narrower scopes to choose from. Crayon does not document which actions each role may take.

Make that API user a dedicated account for StackJack. Do not reuse a person's own login. If that person changes their password, leaves the company or switches on multi-factor sign-in, every Crayon call from StackJack stops, and a wrong password can lock the user out of Cloud-iQ.

Steps

1. Check you have a Tenant administrator account in Cloud-iQ. Crayon's API is for Crayon partners, and its authentication guide says to request a Tenant administrator account from your Crayon contact before using the API. If you do not have one, ask your Crayon contact.
2. Create an API client. Sign in to Cloud-iQ, open the Clients page and create a client for StackJack. Copy its Client ID and Client Secret.
3. Create a dedicated API user. Open the Users page and create a new user used only by StackJack. Give it access to the organizations StackJack should reach. Crayon's guide asks for a Tenant administrator account for API sign-in and does not say what a regular user can do, so if a call is refused, check this user's role first.
4. Keep that user free of a second sign-in factor. StackJack signs in with a user name and password and cannot answer a multi-factor prompt. Crayon does not say whether an API user can be exempt, so if the connection fails with a password you know is right, ask your Crayon contact.
5. Enter the four values in StackJack. Open Connectors, choose Crayon and enter the Client ID, the Client Secret, the API user's user name and the API user's password. There is no address to enter: Crayon's API address is fixed.
6. Optional: enter a default organization ID. If you work in one Crayon organization, enter its numeric ID and the tools that take an optional organization use it whenever your AI does not name one. A request that already names a person (for example, the user who owns a cart or report, or the user who sent it) or a list of organizations is not limited to the default, so it still finds that person's records in every organization. Your AI can list the IDs with the organizations tool.
7. Run a Test Connection. A failure here is almost always one of the four values mistyped, a locked or multi-factor-protected API user, or an API user that Cloud-iQ refuses the organizations list.

Changing these later

Open Configure on the Crayon connector and change what you need. All four values, and the optional default organization ID, are asked for again on every save: nothing is kept when a box is left blank, and an empty default organization ID removes the default. If the API user's password changes in Cloud-iQ, enter the new one here straight away.

If Crayon refuses the sign-in, StackJack does not keep trying. It remembers the refusal for a few minutes so a burst of requests cannot deepen a lockout, and saving the connector again tries immediately.

What to know before your AI uses this connector

Writes here are real money, and Crayon has no sandbox

Placing an order, creating a subscription, creating a new customer tenant, changing seats, status or renewals, adding an add-on, converting or upgrading a subscription, creating or cancelling an Azure subscription and changing a reseller price all buy something or change what a customer is billed, and Crayon offers no test environment to try them in. All of them need the Pro tier, and every one is marked so that your AI application can ask you to confirm before it runs. Whether it does depends on that application's own settings: see Destructive tools and confirmation and review it before you grant the Pro tools.

The marking goes further than purchases. These are also marked, because they cannot be undone or reach further than they look:

• Deleting a customer tenant, user, consumer, invoice profile, grouping, product container, export, set of tags or reseller price.
• Replacing a whole record. Crayon updates customer tenants, users, consumers, accounts, invoice profiles, groupings, assets and subscriptions with a full replace, so a field left out of the request can be cleared. The safe pattern is to read the record, change it and send all of it back, and each tool says so. Setting a subscription's tags works the same way: Crayon replaces the whole tag set, so every tag you leave out is cleared.
• Granting access or storing a password: creating or changing a Cloud-iQ user (which can make a Tenant administrator), changing which organizations a user can reach, changing a user's password, and adding or updating a customer tenant with an administrator login.
• A route whose effect Crayon does not document. Crayon publishes no description of its reserved-instance route, so the tool that writes to it is marked too, and its read twin says the meaning of the answer is unverified.
• Recording a legal consent to a publisher agreement on a customer's behalf. Only do that with the customer's real consent.

Customer tenant answers can contain a password

Crayon's examples for creating, reading in detail, updating and adding an existing customer tenant all show the tenant administrator's user name and password in the answer. StackJack marks those tools as carrying credentials: it never saves their answers and never turns a large one into a stored file, but the values still appear in your AI conversation. Keep them out of tickets and chat. The API user's own profile read also echoes the access token it signed in with, and is marked the same way.

Files come back as a download link

Billing statement files, reconciliation files, the billing records file, export files and the product price-list workbook are not returned as bytes. StackJack stores the file and gives your AI a read-only link that works for thirty minutes, along with the file's name and size. Open it promptly: after that the link stops working and the file has to be fetched again. If a StackJack deployment has no file storage configured, these tools fail with a clear message rather than handing back a link that would not work.

The monthly Azure usage tool answers differently: Crayon itself returns a storage link, also valid for thirty minutes, to the usage CSV. That link works for anyone who holds it, so open it promptly and do not paste it into tickets or chat.

Three usage-cost routes are not in Crayon's API description

Crayon's developer guide documents three usage-cost reads that its published API description leaves out. StackJack includes them next to the documented ones, and each says which documented tool answers the same question.

Lists, pages and what Crayon returns

Crayon numbers pages from one and lets you set a page size. It publishes no maximum, so StackJack caps the page size so one call cannot pull an unbounded amount out of a partner tenant: ask for the next page rather than a bigger one. Crayon's guide shows a list as an object holding the items and a total, while its API description says a plain array, and StackJack has no sandbox to settle it, so every answer is returned exactly as Crayon sends it.

Plans and limits

Read tools are available on the Free tier. Everything that creates, changes, deletes or administers is Pro. Business reaches the same tools as Pro and differs by monthly call quota.

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

Crayon publishes no rate limit, so StackJack paces requests conservatively and backs off on its own if Crayon answers that it is being throttled. Pacing smooths a burst; it does not guarantee that every call arrives, so narrow a very wide read (fewer customers, a shorter date window) rather than repeating it.

Several customers and several tenants

One connection reaches every customer your Cloud-iQ tenant manages, so most partners need only one. Tools that act on a customer take an organization or customer tenant argument, and your AI finds those with the organizations and customer tenants tools first. A second connection is only for a partner that holds accounts with more than one Crayon tenant: add one per tenant from the connector's card, name it after the tenant, and your AI names it on each call. Omit the name and the call runs against your default connection. Pin an endpoint to one connection when an AI should never reach past a single tenant. See Several connections of one connector.

Troubleshooting

"Crayon refused the sign-in StackJack uses": one of the four values was not accepted. Re-enter all four on the Configure dialog: the Client ID and Client Secret from Cloud-iQ Clients, and the API user's user name and password from Cloud-iQ Users. Check that the user can sign in to Cloud-iQ itself, is not locked out after wrong passwords, has no multi-factor prompt and has not had its password changed.

"Crayon accepted the sign-in but refused this action": the connection works, but the API user's role or organization access may not cover that action. Crayon does not document which role each action needs, so check the API user's role under Users in Cloud-iQ, and check it has access to the organization involved. The organization access tool shows what the API user has today.

"Crayon could not find that record": check the ID against the matching list tool and pass it exactly as returned. The same answer appears when the API user has no access to the organization that owns the record.

"Crayon rejected the request as invalid": Crayon's answer names the problem in its message and error fields. Correct what it names and send the request again; repeating the identical call fails the same way. For a write that replaces a whole record, read the record first and send every field back.

A connection test passes but a tool fails on a customer: the test checks that the API user can sign in and open the list of organizations. It does not prove access to every organization, so a customer outside the user's organization access answers as not found or refused.

Something answered, but not Crayon: a proxy, firewall or sign-in page replied instead. StackJack reports that as a failure rather than as success, so a connection test cannot pass against a login screen. Try again in a moment, and check that Crayon's API is reachable from the internet.

Crayon tools

crayon_ · 158 tools · Free 99 · Pro 59

Activity and health

Agreements and consent

Consumers and cloud accounts

Customer tenants

Organizations

Users and access

Assets

Azure Plans

Azure usage

Management links

New Commerce orders

Subscription changes

Subscriptions

Billing statements

Catalog

Exports

Invoicing

Ordering

Product containers

Reseller prices

Usage cost