The connector contract defines a fixed set of events the Admin Module can invoke on a connected portal. Each is a POST to a path under /connector.

Status legend — Live: implemented and responding. Reserved: defined in the contract; returns "not implemented yet" until the connector phase is completed on your deployment.

Identity

`ping` — Live

Liveness check and identity handshake.

POST /connector/ping

// Request
{ timestamp: string }
 
// Response
{ pluginSlug: string; ok: true; timestamp: string }

Stats

`stats.summary` — Reserved

Aggregate totals for the central dashboard.

POST /connector/stats

// Response
{ totalUsers: number; totalLicenses: number; activeLicenses: number }

Users

Event	Path	Status	Purpose
`user.list`	`/connector/users/list`	Reserved	Page through users
`user.get`	`/connector/users/get`	Reserved	Fetch one user
`user.suspend`	`/connector/users/suspend`	Reserved	Suspend a user
`user.unsuspend`	`/connector/users/unsuspend`	Reserved	Restore a user

// user.suspend request
{ userId: string; reason: string }
// → { success: boolean }

Licenses

Event	Path	Status	Purpose
`license.list`	`/connector/licenses/list`	Reserved	Page through licenses
`license.revoke`	`/connector/licenses/revoke`	Reserved	Permanently invalidate a key
`license.activate`	`/connector/licenses/activate`	Reserved	Force an activation

Plans

`plans.sync` — Reserved

Push updated plan definitions from the Admin Module down to this deployment.

POST /connector/plans/sync

// Request
{ plans: Array<Record<string, unknown>> }
// → { synced: number }

Response envelope

Every connector handler returns a Result:

// Success
{ ok: true, data: { /* event-specific */ } }
 
// Failure
{ ok: false, error: string }

This means callers check ok rather than catching exceptions for expected failures (unknown user, unimplemented event, etc.).

Authentication

All events require the connector headers described in the Security Model. Requests without a valid x-connector-token are rejected before any handler runs.

Events Reference