Partner API reference

Every Marketplace query and mutation, API scope and webhook topic in the Vectis Partner API.

Public queries

These need no authentication.

Query	Description	Parameters
`marketplaceApplications`	Browse published apps	`categorySlug?`, `search?`
`featuredApplications`	Featured apps for the Marketplace home	—
`marketplaceApplication`	Application detail by ID	`id`
`marketplaceCategories`	All active categories	—
`apiScopes`	All available API scopes	—
`webhookTopics`	All available webhook topics	—

Authenticated queries

Query	Description	Parameters
`installedApplications`	Your organisation's installed apps	—
`installedApplication`	Installation detail	`installationId`
`installationScopes`	Scope grants for an installation	`installationId`
`webhookDeliveries`	Delivery log for a subscription	`subscriptionId`, `limit?`
`partnerApiRequestLogs`	API request log for an installation	`installationId`, `limit?`
`myPartner`	The current user's partner account	—
`partnerApplications`	Apps belonging to a partner	`partnerId`

Partner mutations

Mutation	Description	Permission
`registerPartner`	Register a partner account	Public
`createApplication`	Create an app	Authenticated
`updateApplication`	Update app details	Authenticated
`submitApplicationForReview`	Submit an app for review	Authenticated
`publishApplication`	Publish an approved app	Authenticated
`deprecateApplication`	Deprecate a published app	Authenticated
`submitVersion`	Submit a new app version	Authenticated
`rotateClientSecret`	Rotate the OAuth client secret	Authenticated

OAuth2 mutations

Mutation	Description	Permission
`oAuthToken`	Issue access and refresh tokens	Public
`oAuthRefreshToken`	Refresh an access token	Public
`oAuthRevokeToken`	Revoke a token	Public
`oAuthIntrospect`	Check a token's validity and details	Public

Organisation operations

Mutation	Description	Permission
`installApplication`	Install an app for your organisation, with `applicationId` and `grantedScopeIds`	`marketplace.install`
`uninstallApplication`	Uninstall an app from your organisation	`marketplace.manage`
`grantScope`	Grant a scope to an installation	`marketplace.manage`
`revokeScope`	Revoke a scope from an installation	`marketplace.manage`
`subscribeWebhook`	Subscribe an installation to a webhook topic, with an `endpointUrl`	`marketplace.manage`
`unsubscribeWebhook`	Unsubscribe from a webhook topic	`marketplace.manage`
`updateWebhookEndpoint`	Change a subscription's endpoint URL	`marketplace.manage`
`rotateWebhookSecret`	Rotate an installation's webhook signing secret	`marketplace.manage`
`sendTestWebhook`	Send a test event to a subscription's endpoint	`marketplace.manage`

For example, to subscribe an installation to a topic:

graphql

mutation {
  subscribeWebhook(
    input: {
      installationId: "installation-id"
      topicId: "topic-id-for-booking-created"
      endpointUrl: "https://partner-app.com/webhooks/vectis"
    }
  ) {
    success
    subscription {
      id
      endpointUrl
      isActive
    }
    error
  }
}

API scopes

Scopes follow the {resource}:{action} pattern. Sensitive scopes are flagged and need explicit consent.

Code	Display name	Resource group	Sensitive
`vehicles:read`	Read Vehicles	Vehicles	No
`vehicles:write`	Write Vehicles	Vehicles	No
`bookings:read`	Read Bookings	Bookings	No
`bookings:write`	Write Bookings	Bookings	No
`fuel:read`	Read Fuel Data	Fuel	No
`fuel:write`	Write Fuel Data	Fuel	No
`ruc:read`	Read RUC Data	RUC	No
`ruc:write`	Write RUC Data	RUC	No
`users:read`	Read Users	Users	Yes
`pools:read`	Read Pools	Pools	No
`trips:read`	Read Trips	Trips	No
`inspections:read`	Read Inspections	Inspections	No
`telematics:read`	Read Telematics	Telematics	No
`expenses:read`	Read Expenses	Expenses	No
`expenses:write`	Write Expenses	Expenses	No
`tolls:read`	Read Tolls	Tolls	No
`tolls:write`	Write Tolls	Tolls	No
`odometer:read`	Read Odometer	Odometer	No
`odometer:write`	Write Odometer	Odometer	No
`organisation:read`	Read Organisation	Organisation	Yes

Webhook topics

Events that partner applications can subscribe to.

Code	Display name	Resource group
`booking.created`	Booking Created	Booking
`booking.updated`	Booking Updated	Booking
`booking.cancelled`	Booking Cancelled	Booking
`booking.checked_out`	Booking Checked Out	Booking
`booking.checked_in`	Booking Checked In	Booking
`vehicle.created`	Vehicle Created	Vehicle
`vehicle.updated`	Vehicle Updated	Vehicle
`fuel.created`	Fuel Transaction Created	Fuel
`odometer.recorded`	Odometer Recorded	Odometer
`inspection.completed`	Inspection Completed	Inspection
`trip.completed`	Trip Completed	Trip

Webhook delivery statuses are Pending, Delivered, Failed and DeadLettered.

Authentication summary

Partner API access: OAuth2 client credentials grant. Partners authenticate with client_id and client_secret to receive bearer tokens.
Access tokens: valid for 1 hour, sent as Authorization: Bearer <token>.
Refresh tokens: valid for 30 days and single-use, rotated on each refresh. Reusing one revokes the whole token family.
Client secret rotation: the previous secret stays valid for 24 hours.

Public queries#

Authenticated queries#

Partner mutations#

OAuth2 mutations#

Organisation operations#

API scopes#

Webhook topics#

Authentication summary#