Pubblicare la bozza di branding

POST /v1/branding:publish · permesso branding:write

Crea uno snapshot di tutte le bozze (ambiente, applicazioni, organizzazioni, testi) e lo rende la versione attiva delle pagine ospitate. Prima della pubblicazione viene verificato il tema effettivo di ogni ambito: token obbligatori, intervalli di valori e contrasto WCAG di ogni coppia di colori. Qualsiasi problema rifiuta l'intera pubblicazione con 422 branding_validation_failed e un elenco issues[] che indica ogni token da modificare (per il contrasto con il ratio misurato, la threshold e la suggestion conforme più vicina). Vengono conservate le ultime 50 versioni. Idempotency-Key è facoltativo.

Se la bozza contiene CSS personalizzato, viene anche visualizzato sulle schermate ospitate prima di qualsiasi pubblicazione (un controllo di rendering che può richiedere fino a 25 secondi; usare un timeout client di almeno 30 secondi). Il CSS che rompe un elemento protetto o aggiunge una violazione di accessibilità che la pagina non ha senza di esso rifiuta la pubblicazione con 422 branding_validation_failed e un elenco render_violations[]. Se la bozza cambia durante il controllo, non viene pubblicato nulla e si riceve 409 conflict; pubblicare di nuovo.

Richiesta

Questa operazione non accetta campi di percorso, query o corpo. L'ambiente deriva dalla credenziale.

Risposta

200 OK con i metadati della nuova versione (lo snapshot non viene restituito).

{
  "version": 4,
  "snapshot_sha256": "3f1c…",
  "source": "publish",
  "rolled_back_from": null,
  "actor_type": "api_key",
  "actor_id": "key_01jb…",
  "published_at": "2026-10-05T09:31:00Z"
}

{
  "type": "https://docs.keenauth.com/problems/branding_validation_failed",
  "status": 422,
  "code": "branding_validation_failed",
  "issues": [
    {"scope_type": "environment", "code": "brand_contrast_insufficient", "field": "light.color.primary_contrast",
     "variant": "light", "pair": "primary_contrast_on_primary", "ratio": 2.1, "threshold": 4.5, "suggestion": "#ffffff"}
  ]
}

Un rifiuto del controllo di rendering elenca ogni riscontro: screen (ad esempio password), locale (en, ar o ja), width (larghezza della viewport in pixel CSS, 320 o 1280), rule (protected_no_area, protected_not_visible, protected_transparent, protected_covered, protected_contrast oppure un ID di regola axe-core come color-contrast) e target (il nome dell'elemento protetto o un selettore CSS axe-core). I valori CSS non vengono mai restituiti. Vengono restituiti al massimo 100 riscontri; render_violations_truncated è true se ce n'erano di più.

{
  "type": "https://docs.keenauth.com/errors/branding_validation_failed",
  "status": 422,
  "code": "branding_validation_failed",
  "render_violations": [
    {"screen": "recovery", "locale": "ar", "width": 320, "rule": "protected_covered", "target": "recovery_codes_hint"}
  ],
  "render_violations_truncated": false
}

Errori

HTTP	code	Quando
403	`plan_feature_unavailable`	La bozza contiene CSS personalizzato o un modello di pagina non incluso nel piano (`feature` indica quale).
422	`branding_validation_failed`	La bozza non può essere pubblicata; vedere `issues[]`. Il CSS personalizzato della bozza viene sanificato di nuovo alla pubblicazione; se non lo supera, le violazioni sono nell'estensione `violations[]` (vedere `PUT /v1/branding/css`). Se il CSS personalizzato non supera il controllo di rendering, i riscontri sono in `render_violations[]` e `render_violations_truncated`.
409	`conflict`	La bozza è cambiata mentre il suo CSS personalizzato veniva controllato; non è stato pubblicato nulla. Pubblicare di nuovo.
401	`unauthenticated`	La credenziale manca, non è valida o è stata revocata.
403	`insufficient_permissions`	La credenziale non ha il permesso richiesto.
429	`rate_limited`	Il limite di frequenza è stato superato; riprovare dopo il periodo `Retry-After`.
503	`service_unavailable`	Una dipendenza è temporaneamente non disponibile (incluso il controllo di rendering di una bozza con CSS personalizzato); riprovare dopo il periodo `Retry-After`.

Esempio

curl -X POST https://api.eu.keenauth.com/v1/branding:publish \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)"