# Berechtigung aktualisieren

`PATCH /v1/permissions/{permission_id}` · Berechtigung `apis:write`

Aktualisiert eine Berechtigung mit einem JSON-Merge-Patch (RFC 7396, `application/merge-patch+json`): Die Felder, die Sie senden, ändern sich, die anderen bleiben. Berechtigungen haben keine Version, daher gibt es kein `If-Match`.

## Anfrage

| Parameter | In | Beschreibung |
|---|---|---|
| `permission_id` | path | Berechtigungs-ID (`perm_…`). |

Body: beliebige der folgenden Felder (alle optional, mindestens eines).

| Feld | Typ | Erforderlich | Beschreibung |
|---|---|---|---|
| `value` | Zeichenkette | nein | Wird nur akzeptiert, wenn er dem aktuellen Wert entspricht; er ändert sich nie. |
| `display_name` | Zeichenkette \| null | nein | Kurzer Name, der auf dem Zustimmungsbildschirm anstelle des Scope-Werts angezeigt wird. Höchstens 128 Zeichen. |
| `description` | Zeichenkette \| null | nein | Detailzeile unter dem Namen auf dem Zustimmungsbildschirm. Höchstens 1024 Zeichen. |
| `consent_text_i18n` | Objekt \| null | nein | Sprachkennung → Text des Zustimmungsbildschirms, zum Beispiel `{"en": "Read your orders"}`. Höchstens 30 Sprachen, jeder Text 1–1024 Zeichen, insgesamt 16 KiB. |
| `sensitivity` | Zeichenkette | nein | `normal` (Standard) oder `sensitive`. |

`display_name`, `description` und `consent_text_i18n` werden mit `null` geleert; `sensitivity` kann nicht geleert werden. `consent_text_i18n` wird als Ganzes ersetzt: Sprachen, die Sie weglassen, werden entfernt, senden Sie daher jede Sprache, die Sie behalten möchten.

### Texte des Zustimmungsbildschirms

Der gehostete Zustimmungsbildschirm zeigt jeden angeforderten Scope so an: der Eintrag `consent_text_i18n` für die Seitensprache (exakte Kennung, sonst deren Haupt-Subtag), sonst `display_name`, sonst der Scope-`value`; `description` wird als Detailzeile angezeigt. Alle drei sind Klartext. Steuerzeichen (einschließlich Zeilenumbrüchen und Tabulatoren), Zeilen- und Absatztrennzeichen sowie bidirektionale Einbettungs-, Überschreibungs- und Isolationszeichen (U+202A-U+202E, U+2066-U+2069) werden mit `422` abgelehnt. Führende und nachfolgende Leerzeichen werden entfernt; ein Text, der danach leer ist, wird als `null` gespeichert. HTML wird nicht interpretiert: Der Zustimmungsbildschirm maskiert es.

## Antwort

`200 OK`

```json
{
  "id": "perm_01h455vb4pex5vsknk084sn02s",
  "api_id": "api_01h455vb4pex5vsknk084sn02q",
  "value": "read:orders",
  "display_name": "Read orders",
  "description": "See your past orders and their status",
  "consent_text_i18n": {
    "en": "Read your orders",
    "tr": "Siparişlerinizi okuyun"
  },
  "sensitivity": "normal"
}
```

## Fehler

| HTTP | code | Wann |
|---|---|---|
| 400 | `unknown_field` | Der Patch enthält `api_id` oder ein unbekanntes Feld. |
| 404 | `not_found` | Es gibt in dieser Umgebung keine solche Berechtigung. |
| 409 | `conflict` | Die Berechtigung gehört zur System-API. |
| 415 | `unsupported_media_type` | Der Content-Type ist nicht `application/merge-patch+json`. |
| 422 | `validation_failed` | Der Patch ist leer, ein Wert ist ungültig oder kein Klartext, `sensitivity` ist `null`, oder `value` weicht ab (`immutable`). |

## Beispiel

```bash
curl -X PATCH https://api.eu.keenauth.com/v1/permissions/perm_01h455vb4pex5vsknk084sn02s \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY" \
  -H "Content-Type: application/merge-patch+json" \
  -d '{"description":"See your past orders and their status","consent_text_i18n":{"en":"Read your orders","tr":"Siparişlerinizi okuyun"}}'
```