Protocolo WebBlocks Support 1.0

WebBlocks CMS y otros productos utilizan este protocolo para conectar una instalación a un proveedor de soporte sin darle a la instalación una cobertura para toda la organización. credencial. WebBlocks Workbench es un proveedor; Las agencias pueden implementar el mismo contrato en su propio origen HTTPS.

Descubrimiento

GET /.well-known/webblocks-support devuelve JSON:

{
  "protocol": "webblocks-support",
  "version": "1.0",
  "name": "Example Support",
  "api_base_url": "https://support.example.com/api/webblocks-support/v1",
  "capabilities": ["ticket.create", "ticket.list", "ticket.read", "ticket.reply", "diagnostics.request", "diagnostics.consent"],
  "activation_methods": ["invitation_code"]
}

La URL de descubrimiento y la URL base de API deben utilizar el mismo origen HTTPS público. No se siguen las redirecciones. CMS 1.0 requiere los cuatro tickets capacidades.

Activación de instalación

POST {api_base_url}/activations acepta:

{
  "install_ref": "random-install-uuid",
  "product": "webblocks-cms",
  "product_version": "1.74.0",
  "site_url": "https://example.com",
  "environment": "production",
  "invitation_code": "WBS-ABCD-EFGH-IJKL"
}

La invitación debe ser válida, no utilizada y emitida para el producto solicitado. eso se consume atómicamente cuando se crea la activación. El proveedor devuelve un secreto de activación para sondeo y código de referencia de cara al usuario: 

{
  "activation_id": "act_123",
  "activation_secret": "one-install-polling-secret",
  "user_code": "ABCD-EFGH",
  "expires_at": "2026-08-28T14:00:00Z"
}

No se requiere inicio de sesión de proveedor ni página de activación externa. el proveedor El operador revisa la solicitud respaldada por invitación y las encuestas de CMS. GET {api_base_url}/activations/{activation_id} con el secreto de activación como token al portador. Una respuesta pendiente es {"status":"pending"}. Una vez aprobado devuelve:

{
  "status": "active",
  "credential": "installation-scoped-bearer-secret",
  "plan_name": "Support",
  "entitlement_expires_at": "2027-08-28T00:00:00Z"
}

La credencial debe limitarse a un producto e instalación. no debe permitir la organización, proyecto, plan u otra administración de instalación.

Entradas

Atodas las llamadas de ticket se autentican con la credencial de instalación. Los puntos finales son relativos a api_base_url:

  • POST /tickets
  • GET /tickets?external_user_ref=...&install_ref=...
  • GET /tickets/{ticket}?install_ref=...
  • POST /tickets/{ticket}/comments
  • DELETE /installation para revocar la credencial de instalación

La creación de boletos incluye title, body, type, external_user_ref, external_user_name, install_ref, product, product_version, site_url y environment. El proveedor deriva su proyecto y derecho del credencial; el cliente nunca proporciona una identificación de proyecto.

La lectura de tickets debe limitarse por credenciales y install_ref. Antes de mostrar un ticket, el CMS también comprueba external_user_ref, por lo que un administrador no puede leer el ticket de otro adivinando su identificador.

Un proveedor que anuncie diagnostics.request puede incluir pendientes diagnostic_requests en GET /tickets/{ticket}. Cada solicitud contiene un identificación opaca y un conjunto de categorías incluidas en la lista permitida: system_summary, recent_application_errors y plugin_health.

La instalación debe mostrar esas categorías al propietario del billete y recibir un aprobación explícita antes de recoger o enviar cualquier cosa. Este responde con POST /tickets/{ticket}/diagnostics/{diagnostic} y cualquiera {"action":"decline"} o {"action":"submit","snapshot":{...}}. La instantánea tiene un límite de 64 KiB y puede contener solo las categorías solicitadas.

El protocolo nunca acepta una ruta del sistema de archivos ni un comando arbitrario. Diagnóstico la colección excluye .env, credenciales, cookies y registros completos; error reciente Las líneas están delimitadas y redactadas localmente antes de la transmisión. Los proveedores retienen las marcas de tiempo de solicitud, consentimiento y envío como pista de auditoría.

Manejo secreto

Las credenciales de activación e instalación son secretos de servidor a servidor. ellos nunca debe ser devuelto a un navegador, registrado, colocado en un sitio exportado o expuesto nuevamente en la interfaz de usuario. CMS los almacena cifrados con su clave de aplicación.