# ブランディングのプレビュー リンクを作成

`POST /v1/branding:preview-link` · 権限 `branding:write`

公開前の環境の現在のブランディング下書きを使って、ホストされたログインページを表示するリンクを作成します。ページには常に最新の下書きが描画されます。下書きを変更したらページを再読み込みすると、変更が表示されます。ページにはプレビューであることを示すバナーが表示され、サインイン操作はすべて無効になります。下書きのテキスト上書きはページの言語で表示されますが、プレビューバナーを変更することはできません。

リンクの有効期間は 10 分で、取り消すことはできません。期限が過ぎると `404` を返します。リンクを知っている人は誰でも下書きを閲覧できるため、デザインをレビューする人にのみ共有してください。1 つの環境で同時に有効にできるリンクは最大 20 件です。

## リクエスト

本文は省略可能です。本文がない場合、ページには環境の下書きのみが表示されます。

| フィールド | 型 | 必須 | 説明 |
|---|---|---|---|
| `application_id` | string | いいえ | このアプリケーションの下書きも適用します (`app_…`)。 |
| `org_id` | string | いいえ | この組織の下書きも適用します (`org_…`)。ロゴとメインカラーが対象です。 |

## レスポンス

`200 OK`。`url` はこのレスポンスでのみ返され、`Cache-Control: no-store` が付きます。同じ `Idempotency-Key` で再送したリクエストは `url` を返さず、`secret_redacted: true` を返します。その場合は新しいリンクを作成してください。

```json
{
  "url": "https://acme.eu1.keenauth.app/u/preview?token=…",
  "expires_at": "2026-10-19T12:10:00Z"
}
```

## エラー

| HTTP | code | 発生条件 |
|---|---|---|
| 400 | `unknown_field` | 本文に不明なフィールドがあるか、JSON オブジェクトではありません。 |
| 404 | `not_found` | この環境にアプリケーションが存在しません。 |
| 422 | `validation_failed` | `application_id` または `org_id` が有効な ID ではありません (`invalid_value`)。 |
| 401 | `unauthenticated` | 認証情報がない、無効である、または取り消されています。 |
| 403 | `insufficient_permissions` | 認証情報に必要な権限がありません。 |
| 429 | `rate_limited` | 環境に有効なリンクがすでに 20 件あるか、レート制限を超えました。`Retry-After` の時間が過ぎてから再試行してください。 |
| 503 | `service_unavailable` | 依存先が一時的に利用できません。`Retry-After` の時間が過ぎてから再試行してください。 |

## 例

```bash
curl -X POST https://api.eu.keenauth.com/v1/branding:preview-link \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"application_id":"app_01jb…"}'
```

CLI を使う場合:

```bash
keenauth branding preview-link --application-id app_01jb…
```