Description
This article covers how to create a ConnectWise API key for ConnectWise integration with Converge.
The integration only needs access to a small number of ConnectWise modules. Rather than granting the API member full Administrator rights, we recommend creating a dedicated Security Role scoped to just those modules. This limits what the integration can reach and reduces your exposure if the API keys are ever compromised.
Requirements
- ConnectWise login with permission to manage Security Roles and Members
Part 1 — Create the Security Role
Create this first, so it's available to select when you create the API member.
- Log into ConnectWise
- Go to System
- Click on Security Roles
- Click the + to add a new Security Role
- Give it an identifiable name, for example
Converge API - Set the following permissions, and leave every other module at Disallow
| Module | Permission | Reason |
|---|---|---|
| Companies > Company Maintenance | Inquire | Looking up and matching your customer company records against Converge billing data. |
| System > Table Setup | Add & Inquire | Reading reference tables (units of measure, etc.) used when writing product and agreement records. |
| Procurement > Product Catalog | Add & Inquire | Creating and reading catalogue items for billed products. |
| Finance > Agreements | Inquire, Add & Edit | Pushing usage and quantity updates to agreement line items. |
| Finance > Billing/Invoicing | Inquire | Only required if the integration needs to read invoice or billing status. |
- Click Save
Optional — tighten the scope further. Where your configuration allows it, you can narrow these permissions beyond module level:
- Finance > Agreements — use the Customise link to restrict access to the specific agreement type(s) Converge writes to, instead of leaving it at All. If you do this, include any parent agreement types as well, or writes may fail.
- Companies > Company Maintenance — Inquire access can be limited by company status or type rather than granted across all companies.
- Board restrictions — if board-level exclusions apply in your environment, enable Callback Member Board Restrictions under System > Setup Tables > Manage Labs so API access respects those exclusions.
Part 2 — Create the API Member
- Go to System
- Click on Members
- Select API Members
- Click the + to add a new API Member
- Fill out the details. The Member ID, First Name and Last Name are visible to your user. We recommend naming this along the lines of your custom branding.
- Set the Role ID field to the Security Role you created in Part 1, for example
Converge API
Click Save once all required fields are filled - Click on the new user created
- Select API Keys
- Click the + to add a new API Key
- Provide a Description for the API Key
- After saving, a Public Key and Private Key will be displayed
(The Private Key is shown once only. Copy both keys before closing the window)
If Converge reports an access or permission error after setup, check the Security Role before granting Administrator rights. ConnectWise occasionally changes the permissions behind a given API endpoint between releases, which can cause a previously working scoped role to start failing.
Lodge a support ticket with the exact error message and we can confirm which permission needs adjusting. Switching the API member to Administrator should not be used as a workaround.