ブランディングアセットをアップロードする

POST /v1/branding/assets · 権限 branding:write

ホストされるログインページで使う画像（ロゴ、ファビコン、背景画像）をアップロードします。レスポンスの id は、テーマのフィールド logo、favicon、background_image に設定する値です（ブランディングを更新するを参照）。画像は公開後にログインページへ表示されます。

すべての画像は隔離されたプロセスでデコードされ、最大 1024 × 1024 ピクセルの PNG に再エンコードされます。メタデータはすべて削除されます。ファビコンには 32 px と 180 px の版も作成されます。id は処理後の PNG の SHA-256 です。同じフィールドに同じ画像を再度アップロードすると、既存のアセットが 200 OK で返されます。

受け付ける形式は PNG、JPEG、WebP で、ICO はファビコンのみ受け付けます。SVG は受け付けません。フォントのアップロードは利用できません。

1 つの環境に保存できるアセットは最大 200 個、合計 50 MB です。

リクエスト

本文は multipart/form-data で、ファイルは最大 1 MiB です。

パート 型 必須 説明
kind string はい logo、favicon、background_image のいずれか。
file file はい 画像。最大 1 MiB、各辺 8192 ピクセル以内。

Idempotency-Key を使う場合、再試行では multipart の境界（boundary）を含めて、まったく同じバイト列を送信してください。

レスポンス

新しいアセットには 201 Created、同じフィールドに同じ画像が既にアップロードされている場合は 200 OK を返します。

{
  "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 は、そのアセットとして保存されたすべての PNG のサイズの合計で、クォータに含まれます。

エラー

HTTP code 発生条件
400 malformed_request multipart 本文を読み取れない、または kind と file 以外のパートが含まれています。
401 unauthenticated 認証情報がない、無効である、または取り消されています。
403 insufficient_permissions 認証情報に必要な権限がありません。
403 quota_exceeded 環境に既に 200 個のアセットまたは 50 MB があります。
413 payload_too_large ファイルが 1 MiB を超えています。
415 unsupported_media_type 本文が multipart/form-data ではない、またはファイルが受け付けられない形式です（errors[] の unsupported_media_type、svg_not_allowed、ico_favicon_only）。
422 validation_failed kind または file がないか無効です（フォントの場合は /kind font_upload_disabled）。または画像を使用できません: invalid_image、image_too_large、image_dimensions_too_large、image_output_too_large、image_processing_limit。
422 idempotency_key_reuse 同じ Idempotency-Key が別の本文で使われました。
429 rate_limited レート制限を超えました。Retry-After の時間が経過してから再試行してください。
503 service_unavailable アセットストレージが一時的に利用できません。Retry-After の時間が経過してから再試行してください。

例

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

CLI の場合:

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