Integrations Platform guide

Audience: MSP and organization administrators connecting third-party systems, and platform administrators curating the integration catalogue. Scope: the integration catalogue and setup wizard, outbound webhooks, API keys, entity mapping, sync control, and the guide library.

What it is

The integrations platform is the shared machinery every Solidlio connector runs on: a catalogue of available providers, a setup wizard that collects and encrypts credentials, a mapping layer that pairs external records with Solidlio records, a sync controller, and an outbound webhook system for pushing Solidlio events to your own tools.

This guide covers the substrate. Individual providers — QuickBooks, Microsoft 365, GLPI, Zabbix, ConnectWise Automate, Azure — have their own guides.

Concepts

Concept	What it is
`IntegrationDefinition`	One catalogue row per provider: name, category, scope, setup fields, availability.
`Integration`	One live connection, owned by an organization, holding encrypted credentials.
`IntegrationMapping`	Pairs an external record id with a Solidlio record, per integration and entity type.
`IntegrationSyncLog`	One row per sync run: counts, duration, status, errors.
Webhook	An outbound HTTP destination you own, subscribed to a set of Solidlio events.
`WebhookDelivery`	One attempt to deliver one event, with the response and a retry control.
API key	A scoped credential your systems present to Solidlio to call the API. See section 6.
Guide	A linked how-to document (e.g. a Scribe recording) attached to tickets or services.

Availability and scope

A provider appears in your catalogue only if its scope matches your portal. A provider marked Coming Soon, or one with no implementation behind it, is shown disabled and cannot be set up — the server refuses before any credential is stored. Scope is enforced on reads and on writes alike, so you cannot reach an MSP-only provider from the organization portal by calling the API directly.

Roles and permissions

Action	Minimum role
Browse the catalogue	Any signed-in user
Set up, configure or disconnect	organization administrator
Map entities, trigger syncs	organization administrator
Create and manage webhooks	organization administrator
View webhooks and delivery history	organization administrator
Create and manage API keys	organization administrator
Curate the platform catalogue	platform administrator

Walkthrough — connecting a provider

Open the catalogue — MSP portal: Integrations. Org portal: Integrations. Providers you cannot use are not listed; providers not yet built are shown disabled.
Read the About page — what the integration does, what it will sync, and which credentials you need to gather first.
Run the setup wizard — enter credentials. They are encrypted with AES-256 before storage and never displayed again.
Test the connection — the wizard calls the provider live before saving.
Map entities — pair external records (clients, groups, subscriptions, host groups) with Solidlio organizations, assets or products. Suggestions are name-matched; accept individually or in bulk. You may only map records your own account owns or manages.
Sync — trigger a sync from the wizard or the integration’s detail page. Sync history records each run with counts and any per-record errors.

Walkthrough — outbound webhooks

Use webhooks to push Solidlio events into your own systems.

Go to Settings → Webhooks in your portal.
New webhook — enter the destination URL and choose the events to subscribe to.
Copy the signing secret. It is shown once, at creation. If you lose it, regenerate — which also shows the new secret once, and immediately invalidates the old one.
Verify signatures on your side. Each delivery carries an signature signature computed over {timestamp}.{payload} using your secret.
Check deliveries — open a webhook to see each attempt, its response, and a retry control.

Destination URLs are validated when saved and re-validated at delivery time, including a re-check of the resolved address on the delivery connection itself — so a hostname cannot be repointed at an internal address between validation and request. Private, reserved, loopback, link-local and cloud-metadata addresses are refused.

API keys — what they do and do not do

You can mint scoped API keys with expiry, deactivate them and revoke them. Keys are hashed with one-way hash; the plaintext is shown once, at creation.

Keys authenticate API calls. Present the key on either header:

What a key can do

Rule	Behaviour
Identity	The key acts as the person who minted it, in the key’s own organization, at that person’s membership role. A key can never out-rank its creator.
Revocation	Deactivating the key, letting it expire, deactivating its owner, or removing the owner from the key’s organization all stop it working.
Plan	The account’s plan must grant `apiAccess`. On `READ_ONLY` the key may only use `GET`/`HEAD`/`OPTIONS`; a write answers 403.
Scopes	Each request needs `<resource>:read` or `<resource>:write` for the resource it targets, derived from the path and the HTTP method.
Portals	A key is not a browser session in any portal, so routes behind a `requirePortal()` guard are not reachable with one.

Resources that share a scope: comments and ticket-queues are under tickets; payments, credit-notes and quotes under invoices; tasks and milestones under projects; organizations under contacts.

Errors

Response	Cause
`401 Invalid, expired or revoked API key`	Unknown, deactivated, expired, or owner lost access
`403 This account's plan does not include API access`	The plan does not grant `apiAccess`
`403 This plan's API access is read-only…`	`READ_ONLY` plan, non-safe method
`403 API key is missing the required scope: tickets:write`	Key does not hold the scope the request needs

Operational notes

Failed resolutions are never cached.
lastUsedAt is updated on each resolution. Key usage is in gateway request logs; key lifecycle (create/revoke/rotate) is in the audit log.

Configuration reference

Setting	What it does	If unset
Provider credentials	Authenticates the connection; encrypted at rest	Setup cannot complete
Entity mappings	Routes external records to the right Solidlio tenant	Records land in the connecting org
Webhook events	Which events a destination receives	At least one is required
Webhook secret	Signs every delivery	Generated automatically
API key scopes	What a key would be permitted to do	At least one is required
API key expiry	When a key stops working	No expiry

Troubleshooting

What you see	Cause
A provider is missing from the catalogue	Its scope does not match your portal — e.g. an MSP-only provider viewed from the org portal.
A provider is shown but the button is disabled	It is on the roadmap. There is no implementation to connect to.
Setup returns “not available”	Same cause, reached via the API rather than the tile.
Mapping rejected	The record you mapped to belongs to an organization your account does not own or manage.
Webhook never fires	Check delivery history. A destination that fails validation at delivery time is not called.
Webhook signature does not verify	Sign `{timestamp}.{payload}`, not the payload alone, and use the current secret.
Lost the webhook secret	Regenerate. The old secret stops working immediately.
An API key does not authenticate	Expected — see section 6.
Sync reports zero records	Some providers declare no syncable entity types; check the provider’s own guide.

Limits and known behaviour

API keys authenticate API calls (§6). A key cannot reach a path that is not mapped to a scope resource, and it is not a portal session, so routes behind a requirePortal() guard are not reachable with one.
Guides can be created, linked and deleted, but not edited in the UI.
A generic per-integration sync interval is not offered; each provider’s cadence is set in that provider’s own settings.
Personal (user-level) calendar connections are managed in calendar settings, not in the integration catalogue.
To change them, re-run setup.