Connecting WordPress sites

Use one agent key for your account and paste it into the WP Triage plugin on each site. The plugin handles registration and per-site credentials automatically.

Quick start (production)

  1. Create an account and log in to WP Triage at https://wptriage.app.
  2. Open Agent key (/settings/agent) and click Download Triage Agent Connector (.zip).
  3. On each WordPress site, install the zip via Plugins → Add New → Upload Plugin, then activate Triage Agent Connector.
  4. Back in Agent key, click Generate agent key. Copy the wpa_… value immediately — it is shown once.
  5. Go to Settings → WP Triage:
    • Agent key — the same wpa_… key on every site you manage.
    • (Optional) Advanced → API base URL — only for local/staging; defaults to https://wptriage.app.
  6. Click Save settings. The plugin calls POST /api/v1/agent/connect and stores the site ID and ingest token.
  7. Use Test connection, then Send snapshot now.
  8. Confirm the site appears under Sites in WP Triage with a recent sync time.

Traffic is outbound from WordPress to WP Triage only. No tunnel or inbound firewall rules on the WP Triage host.

Credential types

Credential Prefix Who uses it Scope
Agent key wpa_… WordPress plugin (settings field) POST /api/v1/agent/connect only
Ingest token wpt_… Plugin internally after connect Snapshots + ingest ping for one site
Sanctum PAT (varies) CLI, scripts, integrations Full account API (/me, /sites, etc.)

The ingest token is issued on each successful connect and saved in WordPress options. Operators do not need to copy it manually.

HTTPS site URL

Site registration requires an HTTPS URL. Plain http://localhost will fail unless you use a local HTTPS hostname. The URL should match how you think of the site in your portfolio (www vs non-www matters for matching).

Rotating keys

Action Effect
Generate new agent key (web UI) Revokes the previous wpa_… key. Re-save plugin settings on each WordPress site with the new key.
Save plugin settings Calls agent connect again; issues a new wpt_… ingest token for that site.

Troubleshooting

Symptom Likely cause
Connect fails HTTP 403 on other APIs with agent key Expected — agent keys cannot call /me or /sites.
Connect fails HTTP 422 on url Site URL is not valid HTTPS.
Test connection fails after save API base URL wrong, agent key revoked, or WordPress cannot reach the API over HTTPS.
Site not in dashboard Connect succeeded but no snapshot yet — use Send snapshot now.
Two sites merged Same canonical URL under one account — intentional deduplication.
Local development

Generate the agent key on your local app (/settings/agent), then paste it in the plugin. Use Advanced → API base URL for local Sail: http://laravel.test.

For local WordPress with HTTPS validation, use a local HTTPS hostname (e.g. https://wpfoundry.test:8443) so agent connect passes url:https validation.

Questions? Get in touch.

After sites are connected

When the same finding repeats across many installs, suppress it from the triage view (On this site or On all sites under Suppress issue), the Recurring issues panel on Sites, or Settings → Suppressions. See Suppressing findings for scope and when to pause a site instead.