# Modifier une autorisation

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

Modifie une autorisation avec un correctif de fusion JSON (RFC 7396, `application/merge-patch+json`) : les champs que vous envoyez changent, les autres restent. Les autorisations n'ont pas de version, donc pas de `If-Match`.

## Demande

| Paramètre | Dans | Description |
|---|---|---|
| `permission_id` | path | ID de l'autorisation (`perm_…`). |

Corps : l'un des champs ci-dessous (tous facultatifs, au moins un).

| Champ | Type | Obligatoire | Description |
|---|---|---|---|
| `value` | chaîne | non | Accepté uniquement s'il est égal à la valeur actuelle ; il ne change jamais. |
| `display_name` | chaîne \| null | non | Nom court affiché sur l'écran de consentement à la place de la valeur du scope. 128 caractères au maximum. |
| `description` | chaîne \| null | non | Ligne de détail affichée sous le nom sur l'écran de consentement. 1024 caractères au maximum. |
| `consent_text_i18n` | objet \| null | non | Balise de langue → texte de l'écran de consentement, par exemple `{"en": "Read your orders"}`. 30 langues au maximum, chaque texte de 1 à 1024 caractères, 16 Kio au total. |
| `sensitivity` | chaîne | non | `normal` (par défaut) ou `sensitive`. |

`display_name`, `description` et `consent_text_i18n` s'effacent avec `null` ; `sensitivity` ne peut pas être effacé. `consent_text_i18n` est remplacé en entier : les langues que vous omettez sont supprimées, donc envoyez chaque langue que vous voulez conserver.

### Textes de l'écran de consentement

L'écran de consentement hébergé affiche chaque scope demandé comme suit : l'entrée `consent_text_i18n` pour la langue de la page (balise exacte, sinon sa sous-balise principale), sinon `display_name`, sinon la `value` du scope ; `description` est affichée comme ligne de détail. Les trois sont du texte brut. Les caractères de contrôle (y compris les sauts de ligne et les tabulations), les séparateurs de ligne et de paragraphe, et les caractères de sens bidirectionnel d'imbrication, de substitution et d'isolation (U+202A-U+202E, U+2066-U+2069) sont rejetés avec `422`. Les espaces en début et en fin sont supprimés, et un texte vide après suppression est enregistré comme `null`. Le HTML n'est pas interprété : l'écran de consentement l'échappe.

## Réponse

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

## Erreurs

| HTTP | code | Quand |
|---|---|---|
| 400 | `unknown_field` | Le correctif contient `api_id` ou un champ inconnu. |
| 404 | `not_found` | Cette autorisation n'existe pas dans cet environnement. |
| 409 | `conflict` | L'autorisation appartient à l'API système. |
| 415 | `unsupported_media_type` | Le type de contenu n'est pas `application/merge-patch+json`. |
| 422 | `validation_failed` | Le correctif est vide, une valeur est invalide ou n'est pas du texte brut, `sensitivity` vaut `null`, ou `value` diffère (`immutable`). |

## Exemple

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