Protocole WebBlocks Support 1.0

WebBlocks CMS et d'autres produits utilisent ce protocole pour connecter une installation à un fournisseur de support sans donner à l'installation une portée à l'échelle de l'organisation accréditation. WebBlocks Workbench est un fournisseur ; les agences peuvent mettre en œuvre le même contrat sur leur propre origine HTTPS.

Découverte

GET /.well-known/webblocks-support renvoie 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"]
}

L'URL de découverte et l'URL de base de l'API doivent utiliser la même origine HTTPS publique. Les redirections ne sont pas suivies. CMS 1.0 nécessite les quatre tickets capacités.

Activation de l'installation

POST {api_base_url}/activations accepte :

{
  "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"
}

L'invitation doit être valide, inutilisée et émise pour le produit demandé. Il est consommé atomiquement lorsque l’activation est créée. Le fournisseur renvoie un secret d'activation pour l'interrogation et un code de référence destiné à l'utilisateur : 

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

Aucune connexion de fournisseur ou page d'activation externe n'est requise. Le fournisseur l'opérateur examine la demande sur invitation et les sondages du CMS GET {api_base_url}/activations/{activation_id} avec le secret d'activation comme jeton de porteur. Une réponse en attente est {"status":"pending"}. Une fois approuvé, il renvoie :

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

Les informations d'identification doivent être limitées à un produit et une installation. Il ne faut pas permettre l'administration d'une organisation, d'un projet, d'un plan ou d'une autre installation.

Billets

ATous les appels de ticket s'authentifient avec les informations d'identification d'installation. Les points finaux sont relatifs à api_base_url:

  • POST /tickets
  • GET /tickets?external_user_ref=...&install_ref=...
  • GET /tickets/{ticket}?install_ref=...
  • POST /tickets/{ticket}/comments
  • DELETE /installation pour révoquer les informations d'identification d'installation

La création de tickets comprend title, body, type, external_user_ref, external_user_name, install_ref, product, product_version, site_url et environment. Le prestataire tire son projet et ses droits du informations d'identification ; le client ne fournit jamais d'identifiant de projet.

La lecture des tickets doit être limitée par les identifiants et install_ref. Avant d’afficher un ticket, le CMS vérifie aussi external_user_ref, afin qu’un administrateur ne puisse pas lire le ticket d’un autre en devinant son identifiant.

Un fournisseur annonçant diagnostics.request peut inclure des diagnostic_requests dans GET /tickets/{ticket}. Chaque demande contient un identifiant opaque et un ensemble de catégories sur liste blanche : system_summary, recent_application_errors et plugin_health.

L'installation doit présenter ces catégories au propriétaire du billet et recevoir un approbation explicite avant de collecter ou d’envoyer quoi que ce soit. Il répond avec POST /tickets/{ticket}/diagnostics/{diagnostic} et soit {"action":"decline"} ou {"action":"submit","snapshot":{...}}. L'instantané est limité à 64 Ko et peut contenir uniquement les catégories demandées.

Le protocole n'accepte jamais un chemin de système de fichiers ou une commande arbitraire. Diagnostic la collection exclut .env, les informations d'identification, les cookies et les journaux complets ; erreur récente les lignes sont délimitées et rédigées localement avant la transmission. Les prestataires conservent les horodatages de la demande, du consentement et de la soumission comme piste d'audit.

Gestion des secrets

Les informations d'identification d'activation et d'installation sont des secrets de serveur à serveur. Ils ne doit jamais être retourné à un navigateur, connecté, placé dans un site d'exportation ou exposé à nouveau dans l'interface utilisateur. CMS les stocke chiffrés avec sa clé d'application.