Designthema der Umgebung aktualisieren

PATCH /v1/branding · Berechtigung branding:write

Ändert den Entwurf des Umgebungsdesigns mit einem JSON-Merge-Patch (application/merge-patch+json, RFC 7396). Ein auf null gesetzter Token (oder eine ganze Gruppe wie "light": null) wird gelöscht und erbt wieder; "theme": null löscht jeden Token. Nur geänderte Tokens werden geschrieben; ein Patch, der nichts ändert, behält die Version. Werte werden beim Schreiben geprüft: Farben sind #rgb/#rrggbb, font.size_base 14–18, radius.card 0–24, radius.control 0–16, logo_height 24–80. logo, favicon und background_image müssen auf ein Bild dieser Art verweisen, das mit Ein Brandingasset hochladen hochgeladen wurde; andernfalls schlägt das Feld mit asset_not_found fehl. Der Kontrast wird beim Veröffentlichen geprüft.

Anfrage

Feld Typ Pflicht Beschreibung
If-Match header ja Das ETag des Entwurfs in der zuletzt gelesenen Fassung ("0", falls nie geschrieben). Fehlt es: 428; ist es veraltet: 412.
theme object | null nein Teilweises BrandingTheme; jedes Feld und jede Gruppe darf null sein.

Antwort

200 OK mit dem Umgebungsentwurf und seinem ETag. theme enthält nur die gesetzten Tokens; nicht gesetzte Tokens erben vom Plattform-Standard.

{
  "theme": {"mode": "light", "light": {"color": {"primary": "#0a3d91"}}, "logo_height": 40},
  "css": null,
  "page_template": null,
  "updated_at": "2026-10-05T09:30:00.123456Z"
}

Fehler

HTTP code Wann
400 unknown_field Der Body enthält ein unbekanntes Feld oder ist kein JSON-Objekt.
412 precondition_failed If-Match stimmt nicht mit der aktuellen Version des Entwurfs überein.
415 unsupported_media_type Der Inhaltstyp ist nicht application/merge-patch+json.
422 validation_failed Ein Token-Wert ist ungültig (invalid_value, out_of_range, unknown_token); pointer benennt den Token, z. B. /theme/light/color/primary.
428 precondition_required Der Header If-Match fehlt.
401 unauthenticated Die Anmeldedaten fehlen, sind ungültig oder wurden widerrufen.
403 insufficient_permissions Den Anmeldedaten fehlt die erforderliche Berechtigung.
429 rate_limited Das Ratenlimit wurde überschritten; versuchen Sie es nach der Zeit aus Retry-After erneut.
503 service_unavailable Eine Abhängigkeit ist vorübergehend nicht verfügbar; versuchen Sie es nach der Zeit aus Retry-After erneut.

Beispiel

curl -X PATCH https://api.eu.keenauth.com/v1/branding \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY" \
  -H "Content-Type: application/merge-patch+json" \
  -H 'If-Match: "3"' \
  -d '{"theme":{"light":{"color":{"primary":"#0a3d91"}},"radius":null}}'