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

{
  "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

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