Gradient

Configuring the Gradient Extension

The Gradient integration sends Microsoft 365 licence counts from CIPP to Gradient for billing reconciliation, and can raise alerts in Gradient where your PSA supports ticket creation through it. Accounts and services are created in Gradient automatically from your tenants and their licences, and are then matched to your Synthesize records in Gradient's own interface.

Gradient maintain their own version of this guide, which will usually be more current on the Synthesize side of the setup. See Gradient's CIPP documentation.

Settings

Setting	Description
Enable Integration	Turns the integration on. The remaining settings and the Test and Force Sync buttons stay unavailable until this is enabled and saved.
Gradient Vendor API Key	The vendor key generated against your custom integration in Synthesize.
Gradient Partner API Key	The partner key generated alongside it. Stored securely and masked once saved; leave blank on later saves to keep the existing value.
Enable sending all license information to Gradient	Allows CIPP to push licence counts to Gradient. Without this, no synchronisation takes place, whether scheduled or triggered manually.

Force Sync only queues a synchronisation when Enable sending all license information to Gradient is also on. With the integration enabled but that setting off, the button appears active but nothing is queued.

Gradient does not use CIPP's Tenant Mapping tab. Tenants are published to Gradient as accounts automatically, and matching them to your Synthesize records happens in Gradient's interface rather than in CIPP.

Setting Up the Integration

1

Generate vendor API keys in Synthesize

Sign in to Synthesize, go to Integrations and select Custom. Choose the modules you want to integrate, name the integration something recognisable such as CyberDrain or CIPP, accept the terms and conditions, and generate the API keys. Record both keys before leaving the page.

2

Connect the integration in CIPP

Turn on Enable Integration, then enter the Gradient Vendor API Key and Gradient Partner API Key. Turn on Enable sending all license information to Gradient if you want licence counts synchronised, then select Submit.

3

Test the connection

Select Test. A green banner confirms the keys are correct. This also marks the integration as active on the Gradient side, so it is worth doing before returning to Synthesize.

4

Run the first sync

Select Force Sync. This publishes your tenants to Gradient as accounts and creates a service for each licence in use, giving Synthesize something to map against.

5

Map accounts and services in Synthesize

Return to Synthesize and select the status refresh button for the CIPP integration, then select Next to begin mapping.

Map your accounts by dragging each card from Synthesize on the left onto the matching CIPP entry on the right. Exact matches are mapped for you; the rest can be found using the filter button or the Synthesize search bar. Select Next when finished.

Map your services the same way, then select Next, review, and select Finish.

6

Import usage

Back in CIPP, select Force Sync once more to import usage against the newly mapped services.

How Synchronisation Works

Each run publishes any tenant that does not already exist in Gradient as an account, using the tenant's display name and default domain name. The default domain name is the account identifier, so it is also what ties alerts to the right Gradient account.

For every licence held by a tenant, CIPP looks for a matching service in Gradient by the licence's friendly product name. Where none exists, a service is created automatically under the infrastructure category and hosted email subcategory, which you can adjust in Synthesize afterwards. The count reported against each service is the number of licences purchased rather than the number assigned. Counts are taken from CIPP's last collection of each tenant's data, so a tenant CIPP has not collected licence data for yet is skipped, with a warning in the CIPP logs, until the next collection.

Synchronisation runs automatically once a day, and can be triggered at any time with Force Sync. Both routes require Enable sending all license information to Gradient to be on.

Licences excluded globally in CIPP's licence settings are left out of the counts sent to Gradient. Exclusions that apply only to alerting are still included, so a licence hidden from alerts will continue to be billed.

Alerting and Ticket Creation

When Gradient is enabled, CIPP alerts configured to deliver to a PSA are also sent to Gradient, which can raise a ticket where your PSA supports it. Alerts are addressed to the Gradient account matching the tenant's default domain name, and the account is created first if it does not yet exist.

CIPP checks the delivery status of each alert after sending it, and records a failure in the CIPP logs where Gradient reports that the alert could not be delivered. If tickets are not appearing, the logs are the first place to look.

---

Feature Requests / Ideas

We value your feedback and ideas. Please raise any feature requests on GitHub.