Connection
The one credential that pairs a site with its workspace, and the two directions the site and the platform talk in.
One credential
A managed site accepts exactly one credential: the workspace token, a secret that belongs to the workspace and is installed on every site in it. The platform presents it on every call to the site, and the worker checks it and refuses anything else. There is no per-site password, no API key on the site, and no login through WordPress's own cookies.
Since worker 2.3.0 the site also holds a credential of its own for the calls it makes to the platform, issued by the platform the first time the site reports in and replaced on request. Work the platform hands a site — a backup, an upload to storage, a restore, its own update — is offered only to a site that identified itself with that credential, and every such instruction is signed and valid once. Neither credential is written into a backup, so a restore does not roll the site's connection back to the backup's day.
Keep the two credentials WP Octo has apart:
| What it opens | Where it belongs | |
|---|---|---|
| Workspace token | the worker on a managed site | on the sites |
| API key | the platform's own API | in an integration |
Putting an API key on a site would hand the platform to whoever compromises that site. The worker never asks for one and has nowhere to put it.
Two directions
The platform calls the site to read its inventory, run an update, take or restore a backup, run a health check and update the worker. This is what a host firewall refuses when it decides the platform is a bot — Hosting compatibility.
The site calls the platform on its own schedule: every fifteen minutes by default, sooner when there is work, and less often when the platform asks it to wait. It reports its worker version and environment, any dataset that changed since it last reported, and what happened on the site; the platform answers with what it wants to see in full, any work it has for the site, and when to call next. A site that cannot be reached by the platform therefore still keeps its data current and still does its work, at the cadence its own WP-Cron gives it.
What a host has to allow
- Outbound HTTPS from the site to
wpocto.com. This is the one connection nothing works without. - The platform's calls to the site's own address. A firewall or bot protection that refuses them is reported on the site's Health page with the provider named and the address to allow; the site keeps reporting in the meantime.
A header of its own
Since worker 2.3.0 the platform sends its credential in a header of its own rather than the standard Authorization header, so that a plugin that owns that header — a JWT authentication plugin — or a host that strips it no longer stands in the way. Older workers are sent the standard header. There is nothing to configure on either side.
Redirects
The platform's authenticated calls never follow a redirect. A site that redirects — to https, to www, to another path — is refused when it is added to the dashboard, and a site that starts redirecting later shows as unreachable with the redirect as the cause. Enter the address the site actually answers on.
Caching in front of the site
An authenticated answer must never be stored by a page cache and handed to the next caller. The worker marks every answer to the platform as not cacheable and, on hosts running LiteSpeed Cache — which caches the WordPress REST API by default and ignores the standard headers — tells the cache plugin directly not to store it.