Caricare una risorsa di branding

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

Carica un'immagine per la pagina di accesso ospitata: un logo, un favicon o un'immagine di sfondo. L'id nella risposta è il valore che inserisci nei campi del tema logo, favicon o background_image (vedi Aggiornare il branding); l'immagine compare nella pagina di accesso dopo la pubblicazione.

Ogni immagine viene decodificata in un processo isolato e ricodificata come PNG, al massimo 1024 × 1024 pixel, con tutti i metadati rimossi. Un favicon riceve anche le versioni a 32 px e 180 px. L'id è lo SHA-256 del PNG elaborato: caricare di nuovo la stessa immagine per lo stesso campo restituisce la risorsa esistente con 200 OK.

I formati accettati sono PNG, JPEG e WebP, e ICO solo per i favicon. SVG non è accettato. Il caricamento dei font non è disponibile.

Un ambiente può contenere al massimo 200 risorse e 50 MB in totale.

Richiesta

Il corpo è multipart/form-data, il file può essere lungo al massimo 1 MiB.

Parte Tipo Obbligatoria Descrizione
kind string sì logo, favicon o background_image.
file file sì L'immagine. Al massimo 1 MiB e 8192 pixel per lato.

Con un Idempotency-Key, un tentativo ripetuto deve inviare esattamente gli stessi byte, incluso il boundary multipart.

Risposta

201 Created per una nuova risorsa, 200 OK quando la stessa immagine era già stata caricata per lo stesso campo.

{
  "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 è la dimensione di tutti i PNG memorizzati della risorsa e conta ai fini della quota.

Errori

HTTP code Quando
400 malformed_request Il corpo multipart non può essere letto, oppure contiene parti diverse da un kind e un file.
401 unauthenticated La credenziale manca, non è valida o è stata revocata.
403 insufficient_permissions La credenziale non ha il permesso richiesto.
403 quota_exceeded L'ambiente ha già 200 risorse o 50 MB.
413 payload_too_large Il file supera 1 MiB.
415 unsupported_media_type Il corpo non è multipart/form-data, oppure il file non è in un formato accettato (unsupported_media_type, svg_not_allowed, ico_favicon_only in errors[]).
422 validation_failed kind o file manca o non è valido (/kind font_upload_disabled per i font), oppure l'immagine non può essere usata: invalid_image, image_too_large, image_dimensions_too_large, image_output_too_large, image_processing_limit.
422 idempotency_key_reuse La stessa Idempotency-Key è stata usata con un corpo diverso.
429 rate_limited È stato superato il limite di richieste; riprova dopo il periodo indicato in Retry-After.
503 service_unavailable L'archiviazione delle risorse non è temporaneamente disponibile; riprova dopo il periodo indicato in Retry-After.

Esempio

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

Con la CLI:

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