Connect a Plugin
Step-by-step — register a Customer Portal deployment with the central Admin Module and verify the handshake.
Follow these steps once per plugin deployment you want to manage centrally. Each plugin has its own portal, its own slug, and its own shared secret.
What you'll need
- The portal's API URL (e.g.
https://api.my-plugin.com) - Access to set environment variables on that portal
- Access to the Admin Module to register the plugin
Step-by-step
Generate a shared secret
This secret authenticates the Admin Module to this portal. Generate a strong, random value:
Keep it secret — you'll paste the same value into both sides.
Configure the Customer Portal
Set these environment variables on the portal (the API app), then restart it:
The connector surface is enabled by default. It only accepts requests once
CONNECTOR_SECRET is set — without a secret, every connector call is rejected.
For a fully standalone deployment, leave CONNECTOR_SECRET empty.
Register the plugin in the Admin Module
In the Admin Module, add a new plugin and provide:
| Field | Value |
|---|---|
| Slug | The exact PLUGIN_SLUG (e.g. my-plugin) |
| Portal URL | The portal's API origin (e.g. https://api.my-plugin.com) |
| Service token | The same CONNECTOR_SECRET from step 1 |
The slug must match exactly on both sides. A mismatch is the most common reason the handshake fails.
Verify with a handshake
Confirm the connection with a ping. The Admin Module does this automatically,
but you can test it directly:
A healthy connection returns the plugin's identity:
Confirm in the Admin Module
The plugin should now show as Connected. From here the central dashboard can run the management operations listed in the Events Reference.
Connecting multiple plugins
Repeat the steps for each plugin. Use a distinct slug and a distinct secret per plugin — never share one secret across deployments, so revoking one plugin's access never affects the others.
| Plugin | PLUGIN_SLUG | Secret |
|---|---|---|
| Plugin A | plugin-a | unique secret A |
| Plugin B | plugin-b | unique secret B |
| Plugin C | plugin-c | unique secret C |
Verify the result
Handshake succeeds
The ping above returns ok: true with the correct slug.
Wrong token is rejected
A ping with a bad x-connector-token returns 401 Unauthorized — confirming
the surface is actually protected.