Mettre à jour une API

PATCH /v1/apis/{api_id} · permission apis:write

Met à jour une API avec un correctif de fusion JSON (RFC 7396, application/merge-patch+json) : les champs que vous envoyez changent, les champs omis restent. If-Match est obligatoire. key et identifier ne peuvent pas changer après la création, et l'API système ne peut pas être modifiée. Un correctif qui ne change rien n'écrit rien et conserve la version.

Demande

Paramètre Dans Description
api_id path L'identifiant de l'API.
If-Match header L'ETag de la dernière lecture (obligatoire).

Corps : tout champ writable ci-dessous (tous optionnels). Un champ ne peut pas être supprimé avec null.

Champ Type Obligatoire Description
key string non Clé de configuration stable, ^[a-z0-9_-]{1,64}$. Immuable.
identifier string non Public cible du jeton : une URL https (sans requête ni fragment) ou urn:<nid>:<nss> ; stockée sous forme canonique. Immuable. L'espace de noms urn:idp: est réservé.
name string non 1-128 caractères.
access_token_lifetime_s integer non 60-86400. Par défaut 3600 (600 avec mcp_profile).
token_format string non jwt (par défaut) ou opaque.
rbac_mode string non Mode par lequel les rôles et permissions atteignent le jeton : claims (par défaut) ajoute permissions et org_permissions ; off n'ajoute aucun des deux (org_roles est toujours ajouté) ; enforce les ajoute et limite en plus les scopes accordés aux permissions effectives de l'utilisateur.
allow_offline_access boolean non Par défaut true.
require_resource_indicator boolean non Par défaut false (true avec mcp_profile).
dpop_required boolean non Par défaut false.
mcp_profile boolean non Nécessite un identifier https et require_resource_indicator: true.
first_party_access string non all (par défaut) ou granted_only.
introspection_applications array non Applications (app_…) pouvant introspect les jetons de cette API, au maximum 50, pas de doublons. Uniquement des applications web et m2m du même environnement. La liste est remplacée en tant que tout ; [] la vide, null est refusé.

Applications d'introspection

Le point de terminaison d'introspection (POST <issuer>/oauth2/introspect, RFC 7662) répond active: true pour un jeton d'accès uniquement à deux appelants : l'application à laquelle le jeton a été émis, ou une application dans la liste introspection_applications de l'API nommée dans le aud du jeton. Tous les autres appelants reçoivent active: false, de sorte que les API ne peuvent pas lire les jetons les uns des autres. Seules les applications confidentielles (web, m2m) du même environnement peuvent être répertoriées ; la liste est stockée sous forme d'ensemble et renvoyée dans l'ordre des identifiants. Une application suspendue reste sur la liste mais ne peut pas introspect. La liste de l'API système ne peut pas être écrite.

Réponse

200 OK avec le nouvel ETag :

{
  "id": "api_01h455vb4pex5vsknk084sn02q",
  "key": "orders",
  "identifier": "https://api.example.com/orders",
  "name": "Orders API",
  "is_system": false,
  "access_token_lifetime_s": 3600,
  "token_format": "jwt",
  "rbac_mode": "off",
  "allow_offline_access": true,
  "require_resource_indicator": false,
  "dpop_required": false,
  "mcp_profile": false,
  "first_party_access": "all",
  "introspection_applications": ["app_01h455vb4pex5vsknk084sn02r"],
  "created_at": "2026-10-05T12:00:00Z",
  "updated_at": "2026-10-05T12:00:00Z"
}

Erreurs

HTTP code Quand
400 unknown_field Le correctif contient un champ en lecture seule ou inconnu.
404 not_found Aucune API avec cet identifiant dans cet environnement.
409 conflict L'API est l'API système.
412 precondition_failed If-Match ne correspond pas à la version actuelle.
415 unsupported_media_type Le type de contenu n'est pas application/merge-patch+json.
422 validation_failed Une valeur est invalide, un champ a été défini sur null, ou key / identifier a été modifié.
422 validation_failed Un élément introspection_applications n'existe pas dans cet environnement (unknown_application), n'est pas confidentiel (not_confidential), est un doublon (duplicate) ou n'est pas un identifiant app_… (invalid_value) ; le pointeur nomme l'index dans la demande.
428 precondition_required If-Match manque.

Exemple

curl -X PATCH https://api.eu.keenauth.com/v1/apis/api_01h455vb4pex5vsknk084sn02q \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY" \
  -H "Content-Type: application/merge-patch+json" \
  -H 'If-Match: "1"' \
  -d '{"access_token_lifetime_s":900}'