Subir un recurso de marca
POST /v1/branding/assets · permiso branding:write
Sube una imagen para la página de inicio de sesión alojada: un logotipo, un favicon o una imagen de fondo. El id de la respuesta es el valor que pones en los campos de tema logo, favicon o background_image (consulta Actualizar la marca); la imagen aparece en la página de inicio de sesión después de publicar.
Cada imagen se decodifica en un proceso aislado y se vuelve a codificar como PNG, con un máximo de 1024 × 1024 píxeles y sin metadatos. Un favicon también recibe versiones de 32 px y 180 px. El id es el SHA-256 del PNG procesado, así que subir de nuevo la misma imagen para el mismo campo devuelve el recurso existente con 200 OK.
Los formatos aceptados son PNG, JPEG y WebP, e ICO solo para favicons. SVG no se acepta. No está disponible la subida de fuentes.
Un entorno puede tener como máximo 200 recursos y 50 MB en total.
Solicitud
El cuerpo es multipart/form-data, y el archivo tiene como máximo 1 MiB.
| Parte | Tipo | Obligatorio | Descripción |
|---|---|---|---|
kind |
string | sí | logo, favicon o background_image. |
file |
file | sí | La imagen. Como máximo 1 MiB y 8192 píxeles por lado. |
Con un Idempotency-Key, un reintento debe enviar exactamente los mismos bytes, incluido el separador del multipart.
Respuesta
201 Created para un recurso nuevo, 200 OK cuando la misma imagen ya se había subido para el mismo 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 es el tamaño de todos los PNG almacenados del recurso y cuenta para la cuota.
Errores
| HTTP | code | Cuándo |
|---|---|---|
| 400 | malformed_request |
El cuerpo multipart no se puede leer o tiene partes distintas de un kind y un file. |
| 401 | unauthenticated |
La credencial falta, no es válida o está revocada. |
| 403 | insufficient_permissions |
La credencial no tiene el permiso requerido. |
| 403 | quota_exceeded |
El entorno ya tiene 200 recursos o 50 MB. |
| 413 | payload_too_large |
El archivo supera 1 MiB. |
| 415 | unsupported_media_type |
El cuerpo no es multipart/form-data, o el archivo no es un formato aceptado (unsupported_media_type, svg_not_allowed, ico_favicon_only en errors[]). |
| 422 | validation_failed |
kind o file falta o no es válido (/kind font_upload_disabled para fuentes), o la imagen no se puede usar: invalid_image, image_too_large, image_dimensions_too_large, image_output_too_large, image_processing_limit. |
| 422 | idempotency_key_reuse |
La misma Idempotency-Key se usó con un cuerpo distinto. |
| 429 | rate_limited |
Se superó el límite de tasa; reintenta después del periodo de Retry-After. |
| 503 | service_unavailable |
El almacenamiento de recursos no está disponible temporalmente; reintenta después del periodo de Retry-After. |
Ejemplo
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