# Ein Rechtsdokument veröffentlichen

`POST /v1/legal-documents` · Berechtigung `legal-documents:write`

Veröffentlicht eine Version eines Rechtsdokuments. KeenAuth ruft `url` einmal über seinen Egress-Proxy ab und speichert den SHA-256-Hash des Bodys als `content_sha256`: nur HTTPS, private und Plattformadressen gesperrt, höchstens 5 MiB, 10 Sekunden; eine Antwort ungleich 200 oder ein leerer Body gilt als nicht erreichbar, und nichts wird gespeichert. `url`, `version`, `locale` und der Hash ändern sich nach der Veröffentlichung nie. `effective_at` ist standardmäßig jetzt und darf nicht in der Vergangenheit liegen.

## Anfrage

JSON-Body (unbekannte Felder werden mit `400 unknown_field` abgelehnt):

| Feld | Typ | Erforderlich | Beschreibung |
|---|---|---|---|
| `Idempotency-Key` | header | nein | Optionaler Schlüssel (16–64 Zeichen), der einen wiederholten Request sicher macht. |
| `kind` | string | ja | `terms`, `privacy_notice` oder `custom`. |
| `version` | string | ja | Ihr Versionslabel, 1–64 Zeichen. |
| `locale` | string | ja | BCP-47-Sprach-Tag; muss in der Umgebung aktiviert sein. |
| `url` | string | ja | Von Ihnen gehostete HTTPS-Seite, höchstens 2048 Byte. |
| `application_id` | string \| null | nein | Anwendung, für die das Dokument gilt (`app_…`); fehlt oder `null` bedeutet alle Anwendungen der Umgebung. |
| `effective_at` | string (date-time) | nein | Zeitpunkt des Inkrafttretens; standardmäßig jetzt, nicht in der Vergangenheit. |
| `requires_reacceptance` | boolean | nein | Bei `true` sehen Benutzer nach `effective_at` bei der nächsten interaktiven Anmeldung den Bildschirm zur erneuten Zustimmung. Standard `false`. |

## Antwort

`201 Created` mit dem Dokument.

```json
{
  "id": "ldoc_01j9xk3m7q8r2s4t6v8w0y2z4a",
  "application_id": null,
  "kind": "terms",
  "version": "2026-10",
  "locale": "en",
  "url": "https://example.com/legal/terms-2026-10",
  "content_sha256": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
  "effective_at": "2026-11-01T00:00:00Z",
  "requires_reacceptance": true,
  "created_at": "2026-10-05T09:30:00.123456Z",
  "updated_at": "2026-10-05T09:30:00.123456Z"
}
```

## Fehler

| HTTP | Code | Wann |
|---|---|---|
| 400 | `unknown_field` | Der Body enthält ein unbekanntes Feld. |
| 409 | `conflict` | Ein Dokument mit derselben Anwendung, demselben Typ, derselben Version und Sprache existiert bereits. |
| 415 | `unsupported_media_type` | Der Content-Type ist nicht `application/json`. |
| 422 | `legal_document_unreachable` | Die URL konnte über den Egress-Proxy nicht abgerufen oder gehasht werden; nichts wurde gespeichert. |
| 422 | `validation_failed` | Ein Feld ist ungültig (zum Beispiel `url` nicht HTTPS, unbekannte `locale`, `effective_at` in der Vergangenheit oder `application_id` nicht in der Umgebung: `unknown_application`). |
| 401 | `unauthenticated` | Die Anmeldedaten fehlen, sind ungültig oder wurden widerrufen. |
| 403 | `insufficient_permissions` | Die Anmeldedaten haben nicht die erforderliche Berechtigung. |
| 429 | `rate_limited` | Die Rate-Grenze wurde überschritten; Wiederhole nach dem `Retry-After`-Zeitraum. |
| 503 | `service_unavailable` | Das Abrufen von Dokumenten ist in dieser Bereitstellung nicht konfiguriert, oder eine Abhängigkeit ist vorübergehend nicht verfügbar. |

## Beispiel

```bash
curl -X POST https://api.eu.keenauth.com/v1/legal-documents \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"kind":"terms","version":"2026-10","locale":"en","url":"https://example.com/legal/terms-2026-10","effective_at":"2026-11-01T00:00:00Z","requires_reacceptance":true}'
```