# Branding-Vorschau-Link erstellen

`POST /v1/branding:preview-link` · Berechtigung `branding:write`

Erstellt einen Link, der die gehostete Anmeldeseite mit den aktuellen Branding-Entwürfen der Umgebung zeigt, bevor sie veröffentlicht werden. Die Seite zeigt immer den neuesten Entwurf: Ändern Sie einen Entwurf und laden Sie die Seite neu, um die Änderung zu sehen. Ein Banner kennzeichnet die Seite als Vorschau, und alle Anmeldeelemente sind deaktiviert. Entwurfstexte werden in der Sprache der Seite angezeigt; sie können das Vorschau-Banner nicht ändern.

Der Link ist 10 Minuten gültig und kann nicht widerrufen werden; danach liefert er `404`. Wer den Link hat, kann den Entwurf sehen. Teilen Sie ihn daher nur mit Personen, die das Design prüfen. Eine Umgebung kann höchstens 20 gültige Links gleichzeitig haben.

## Anfrage

Der Body ist optional. Ohne Body zeigt die Seite nur den Umgebungsentwurf.

| Feld | Typ | Pflicht | Beschreibung |
|---|---|---|---|
| `application_id` | string | nein | Wendet zusätzlich den Entwurf dieser Anwendung an (`app_…`). |
| `org_id` | string | nein | Wendet zusätzlich den Entwurf dieser Organisation an (`org_…`): deren Logo und Primärfarbe. |

## Antwort

`200 OK`. Die `url` wird nur in dieser Antwort zurückgegeben, mit `Cache-Control: no-store`. Eine mit demselben `Idempotency-Key` wiederholte Anfrage liefert keine `url`, sondern `secret_redacted: true`; erstellen Sie stattdessen einen neuen Link.

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

## Fehler

| HTTP | code | Wann |
|---|---|---|
| 400 | `unknown_field` | Der Body enthält ein unbekanntes Feld oder ist kein JSON-Objekt. |
| 404 | `not_found` | Die Anwendung existiert in dieser Umgebung nicht. |
| 422 | `validation_failed` | `application_id` oder `org_id` ist keine gültige ID (`invalid_value`). |
| 401 | `unauthenticated` | Die Anmeldedaten fehlen, sind ungültig oder widerrufen. |
| 403 | `insufficient_permissions` | Den Anmeldedaten fehlt die erforderliche Berechtigung. |
| 429 | `rate_limited` | Die Umgebung hat bereits 20 gültige Links oder das Ratenlimit wurde überschritten; nach der Zeit aus `Retry-After` erneut versuchen. |
| 503 | `service_unavailable` | Eine Abhängigkeit ist vorübergehend nicht verfügbar; nach der Zeit aus `Retry-After` erneut versuchen. |

## Beispiel

```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…"}'
```

Mit der CLI:

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