Partner integrations
How partner applications, scopes, installations and webhooks fit together in the Vectis Marketplace.
The Vectis Marketplace lets third-party companies (partners) build, publish and distribute integrations that extend Vectis. Partners create applications that request specific API scopes (such as vehicles:read or fuel:write) and publish them to the Marketplace catalogue. Organisation administrators install applications, grant scoped data access, and configure webhook event delivery.
| Who | What they do |
|---|---|
| Partner developer | Registers, builds an application, gets tokens and calls the Partner API. |
| Vectis | Reviews and publishes applications, runs the OAuth2 server and webhook system, and enforces scopes. |
| Organisation administrator | Browses and installs applications, grants scopes, configures webhooks and monitors activity. |
Choose your guide
- Organisation administrators: installing and managing partner applications.
- Partners and developers: building a partner integration.
- Both: the API reference, with every scope, webhook topic and operation.
For a quick tour of the Marketplace screens, see Marketplace & integrations.
Key concepts
| Concept | Description |
|---|---|
| Partner | A third-party company registered as a developer on the Vectis platform. |
| Application | A software integration built by a partner and published to the Marketplace. |
| Scope | A granular permission (such as fuel:read or vehicles:write) that controls data access. |
| Installation | An organisation's instance of a Marketplace application, with its granted scopes. |
| OAuth2 client | Credentials (client_id and client_secret) issued to an application for API authentication. |
| Webhook subscription | An installation's registration to receive event notifications. |
| Webhook secret | An HMAC-SHA256 signing key unique to each installation, used to verify webhook payloads. |
Application lifecycle
An application moves through these statuses:
Draft → Submitted → In Review → Approved → Published → Deprecated
A rejected application returns to Draft, so the partner can make changes and resubmit.
Permissions
| Permission | Allows | Typical role |
|---|---|---|
marketplace.view | Browse the Marketplace catalogue | All users |
marketplace.install | Install applications for the organisation | System Administrator |
marketplace.manage | Manage installations, scopes and webhooks | System Administrator |
How access is controlled
- Partner API requests are checked against the installation's granted scopes. Requesting data outside them returns an authorisation error.
- Organisation administrators can grant and revoke scopes at any time. A revoked scope takes effect on the next API call.
- A partner application can only access data belonging to the organisation that installed it.
- Each installation has its own webhook secret. Every webhook payload is signed with it, and the secret can be rotated.