Skip to main content

Authentication

The Manage API accepts two forms of authentication. Both are checked on every request; either one is sufficient.

Two ways to authenticate​

1. SyteOps admin — in-process (session or cookie)​

When a request arrives already authenticated as a WordPress user who holds the SyteOps admin capability (for example, a logged-in admin making a browser-side XHR call or a server-side call using WordPress's own HTTP stack), no additional credentials are needed. The API recognizes the current user context and grants access because that user is a SyteOps admin. A WordPress administrator who is not a SyteOps admin is refused.

This mode is used by the SyteOps admin UI itself.

2. som_ API key via X-API-Key header​

For external tools, automation platforms, and MCP bridges, authentication is performed by sending a secret key in the X-API-Key HTTP request header.

Valid keys are prefixed som_. Example request:

curl -X POST "https://your-site/wp-json/syteops/v1/manage/dispatch" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: som_YOUR_KEY_HERE" \
  -d '{"resource":"status","action":"get"}'

Replace som_YOUR_KEY_HERE with the key you minted from the SyteOps admin UI.

Minting and rotating a key​

API keys are managed entirely from the SyteOps admin UI — no WP-CLI or database access is required.

  1. Open the SyteOps admin panel in your WordPress dashboard.
  2. Navigate to the API Keys section.
  3. Click Generate new key. The key is displayed once — copy it immediately.
  4. To rotate a key, click Rotate next to the existing key. The old key is invalidated immediately and a new one is issued.

Keys are encrypted at rest; SyteOps never stores them in plaintext.

Who may call an operation​

Every operation, on every path, needs one of two things: a signed-in SyteOps admin, or a valid API key. Nothing else is checked at this step.

  • API key: a valid key may call every operation. It is not checked against WordPress capabilities.
  • Signed-in user: the user must be a SyteOps admin. Holding manage_options, or the Administrator role, is not enough.
  • Destructive operations also need confirm: true in the request. See Dispatch contract.

Some operations that act on one post also check that a signed-in user can edit that post. An API-key call skips that check because it has no WordPress user.

A caller who is neither gets HTTP 403 with the error code forbidden.

The capability field in the Manifest is kept for compatibility. The API does not use it to decide access.

warning

API keys are operator secrets. Treat them with the same care as database passwords:

  • Never commit a key to version control.
  • Never log a key in plaintext (application logs, CI output, etc.).
  • Store keys in environment variables or a secrets manager and reference the variable name in configuration files.
  • Rotate immediately if a key is accidentally exposed.