Crayon Cloud-iQ Integration
Connect your Crayon Cloud-iQ partner account so agents can look up your organizations and customer tenants, software subscriptions and pricing, Azure plans and usage, and billing. Every Crayon tool is read-only. Agents cannot order, change or cancel anything in Crayon.
Partner tool. Crayon Cloud-iQ is only available to a tenant that is also an Outermind partner, on Workforce plan and up. The integration card carries a Partner tool badge; a tenant that is not an active partner (including a partner whose billing is suspended) cannot connect it.
Before you start
- A Crayon Cloud-iQ partner account with access to the organizations you want agents to see.
- Permission in Cloud-iQ to create API clients and users.
- A tenant admin in Outermind with permission to manage connections.
Why Crayon needs a user's password
Crayon Cloud-iQ offers only one way for an application to sign in to its API: the OAuth 2.0 resource-owner password grant. The application sends an API client's ID and secret together with a Cloud-iQ user's username and password. There is no sign-in page to redirect to and no client-credentials option, so Outermind has to hold that user's password to keep the connection working.
To keep the exposure small:
- Create a dedicated API user for Outermind rather than using a person's own login. Agents see what that user can see.
- Outermind stores the client ID, client secret, username and password encrypted, and never shows them again after you save them.
- Multi-factor authentication must be off for the API user. The password grant cannot answer an MFA challenge; if MFA is on, token refresh starts failing about 5 hours after you connect.
Prepare Crayon Cloud-iQ
- Create an API client at cloudiq.crayon.com/clients. Note its client ID and client secret.
- Create an API user at cloudiq.crayon.com/users, with access to the organizations agents should see. Note its username (an email address) and password.
- Turn off MFA on that API user.
Connect in Outermind
- Open the Capabilities hub, go to Connections, and open Crayon Cloud IQ. The page is at
/capabilities/integrations/crayon; the form is on the same page. - Click Connect Crayon Cloud-iQ.
- Enter the Client ID, Client Secret, Username and Password, then submit.
- If the credentials can see more than one organization, choose the one to connect under Select Organization.
- Grant the Crayon tools to each agent that needs them from the agent's Tools tab (Workforce > Agents > Agents & SMEs).
If Crayon rejects the credentials, the form says so; check all four values and that MFA is off. The connected page also has a Data Preview of organizations, customers and subscriptions and an Execution Logs list of recent Crayon tool calls by your agents.
What your agents can do
Every action below is class read and tier read, so it runs without asking a person at every autonomy level.
| Tool | Actions | What it covers |
|---|---|---|
crayon_organizations | list, get, list_customers, get_customer, get_customer_details | Your organizations and the customer tenants beneath each one. A password field in customer detail always comes back redacted. |
crayon_subscriptions | list, get, get_unit_price, list_addon_offers, get_coterminosity, list_agreements, list_agreement_products, list_billing_cycles | Subscriptions, per-seat unit prices in their own currency, add-on offers, coterminosity alignment, agreements, their SKU catalog and billing cycles. |
crayon_azure | get_customer_plan, get_plan, list_subscriptions, get_subscription, get_usage | A customer's Azure Plan, its Azure subscriptions and monthly usage cost. |
crayon_billing | list, list_statements, list_invoice_profiles, get_invoice_profile, get_category_costs, get_subscription_costs | Invoices, billing statements, invoice profiles and a customer tenant's usage costs. |
Safety
- Read-only. No Crayon tool has a write, delete or admin action.
- The API user bounds what agents see. Restrict the user in Cloud-iQ to the organizations agents need.
- Rotate the password with care. When you change the API user's password in Cloud-iQ, use Update Credentials on the connection page straight away, or agent calls fail once the current token expires.
Testing and disconnecting
- Test Connection checks that Crayon still accepts the credentials.
- Update Credentials replaces the stored client ID, secret, username and password.
- Disconnect Crayon Cloud-iQ removes the connection and its stored credentials, and unassigns the Crayon tools from every agent. Delete or disable the API user in Cloud-iQ as well if you no longer need it.