Ein Branding-Asset hochladen

POST /v1/branding/assets · Berechtigung branding:write

Lädt ein Bild für die gehostete Anmeldeseite hoch: ein Logo, ein Favicon oder ein Hintergrundbild. Die id in der Antwort ist der Wert, den Sie in die Themenfelder logo, favicon oder background_image eintragen (siehe Branding aktualisieren); das Bild erscheint nach dem Veröffentlichen auf der Anmeldeseite.

Jedes Bild wird in einem isolierten Prozess dekodiert und als PNG neu kodiert, höchstens 1024 × 1024 Pixel, wobei alle Metadaten entfernt werden. Ein Favicon erhält zusätzlich Versionen mit 32 px und 180 px. Die id ist der SHA-256-Hash des verarbeiteten PNG. Wenn dasselbe Bild erneut für dasselbe Feld hochgeladen wird, wird das vorhandene Asset mit 200 OK zurückgegeben.

Akzeptierte Formate sind PNG, JPEG und WebP sowie ICO nur für Favicons. SVG wird nicht akzeptiert. Der Upload von Schriftarten ist nicht verfügbar.

Eine Umgebung kann höchstens 200 Assets und insgesamt 50 MB enthalten.

Anfrage

Der Körper ist multipart/form-data, die Datei darf höchstens 1 MiB groß sein.

Teil Typ Pflicht Beschreibung
kind string ja logo, favicon oder background_image.
file file ja Das Bild. Höchstens 1 MiB und 8192 Pixel pro Seite.

Bei einem Idempotency-Key muss ein Wiederholungsversuch exakt dieselben Bytes senden, einschließlich der Multipart-Begrenzung (Boundary).

Antwort

201 Created für ein neues Asset, 200 OK, wenn dasselbe Bild für dasselbe Feld bereits hochgeladen wurde.

{
  "id": "3f0c…e91a",
  "kind": "favicon",
  "url": "https://acme.eu1.keenauth.app/assets/3f0c…e91a.png",
  "width": 256,
  "height": 256,
  "byte_size": 48213,
  "source_format": "ico",
  "favicon_32_url": "https://acme.eu1.keenauth.app/assets/9b1d…04c2.png",
  "favicon_180_url": "https://acme.eu1.keenauth.app/assets/c7e2…5a10.png",
  "created_at": "2026-10-19T20:30:00Z"
}

byte_size ist die Größe aller gespeicherten PNGs des Assets und zählt auf das Kontingent.

Fehler

HTTP code Wann
400 malformed_request Der Multipart-Körper kann nicht gelesen werden oder enthält andere Teile als ein kind und eine file.
401 unauthenticated Die Anmeldedaten fehlen, sind ungültig oder widerrufen.
403 insufficient_permissions Die Anmeldedaten haben nicht die erforderliche Berechtigung.
403 quota_exceeded Die Umgebung hat bereits 200 Assets oder 50 MB.
413 payload_too_large Die Datei ist größer als 1 MiB.
415 unsupported_media_type Der Körper ist nicht multipart/form-data, oder die Datei hat kein akzeptiertes Format (unsupported_media_type, svg_not_allowed, ico_favicon_only in errors[]).
422 validation_failed kind oder file fehlt oder ist ungültig (/kind font_upload_disabled für Schriftarten), oder das Bild kann nicht verwendet werden: invalid_image, image_too_large, image_dimensions_too_large, image_output_too_large, image_processing_limit.
422 idempotency_key_reuse Derselbe Idempotency-Key wurde mit einem anderen Körper verwendet.
429 rate_limited Das Ratenlimit wurde überschritten; wiederholen Sie die Anfrage nach der Zeitspanne aus Retry-After.
503 service_unavailable Der Asset-Speicher ist vorübergehend nicht verfügbar; wiederholen Sie die Anfrage nach der Zeitspanne aus Retry-After.

Beispiel

curl -X POST https://api.eu.keenauth.com/v1/branding/assets \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY" \
  -F kind=logo \
  -F file=@logo.png

Mit der CLI:

keenauth branding assets upload --kind logo --file logo.png