Abilities API et permissions : encadrer ce qu’un agent IA peut invoquer

L’Abilities API, introduite dans WordPress 6.9 sorti en décembre 2025, propose un mécanisme standardisé pour qu’un site déclare explicitement les actions qu’il expose à des consommateurs externes, humains ou agents, plutôt que de laisser chaque extension inventer sa propre convention de routes REST personnalisées. Ce tutoriel se concentre sur un aspect précis, déjà annoncé dans la documentation de l’API mais rarement détaillé avec des exemples concrets : comment déclarer les permissions d’une ability pour qu’un agent externe ne puisse l’invoquer que dans un périmètre volontairement restreint, sans jamais hériter par défaut d’un accès plus large que nécessaire.

Étape 1 : déclarer une ability avec son schéma d’entrée

Une ability se déclare via la fonction wp_register_ability(), en spécifiant un identifiant unique, une description en langage naturel destinée à être comprise par un agent, et un schéma des paramètres attendus, sur le modèle de JSON Schema :

wp_register_ability( 'monsite/archiver-article', array(
    'label'       => __( 'Archiver un article ancien', 'monsite' ),
    'description' => __( 'Passe un article publié depuis plus de trois ans au statut archive.', 'monsite' ),
    'input_schema' => array(
        'type'       => 'object',
        'properties' => array(
            'article_id' => array( 'type' => 'integer' ),
        ),
        'required' => array( 'article_id' ),
    ),
    'execute_callback'    => 'monsite_executer_archivage',
    'permission_callback' => 'monsite_verifier_permission_archivage',
) );

Cette déclaration ressemble, par sa structure, à l’enregistrement d’une route REST classique. La différence essentielle tient à la nature du permission_callback : il ne se contente plus de répondre à la question habituelle « cet utilisateur a-t-il la capacité requise ? », il reçoit un contexte d’invocation complet, incluant potentiellement l’identité de l’agent qui invoque l’ability, distincte du seul utilisateur WordPress au nom duquel il agit.

Étape 2 : écrire un permission_callback conscient du contexte d’agent

Le permission_callback d’une ability reçoit en paramètre les données d’invocation, ce qui permet d’y intégrer une vérification à plusieurs niveaux, au-delà de la seule capacité WordPress classique :

function monsite_verifier_permission_archivage( $input, $contexte ) {
    // Premier niveau : la capacité WordPress classique, inchangée.
    if ( ! current_user_can( 'edit_posts' ) ) {
        return false;
    }

    // Deuxième niveau : le contexte d'invocation, propre aux abilities.
    if ( ! empty( $contexte['agent_id'] ) ) {
        $agents_autorises = array( 'agent-archivage-2025' );
        if ( ! in_array( $contexte['agent_id'], $agents_autorises, true ) ) {
            return false;
        }
    }

    // Troisième niveau : la donnée métier elle-même.
    $article = get_post( $input['article_id'] );
    if ( ! $article || $article->post_status !== 'publish' ) {
        return false;
    }

    $trois_ans = 3 * YEAR_IN_SECONDS;
    return ( time() - strtotime( $article->post_date_gmt ) ) > $trois_ans;
}

Cette structure en trois niveaux illustre l’apport principal de l’Abilities API par rapport à une route REST personnalisée classique : la capacité de restreindre une ability non seulement à un rôle utilisateur, mais aussi explicitement à une liste d’agents nommés, et de conditionner son exécution à une règle métier vérifiable (ici, l’ancienneté réelle de l’article), plutôt que de faire confiance à ce que l’agent affirme dans sa requête.

Étape 3 : limiter le périmètre d’entrée avec le schéma

Le schéma d’entrée déclaré à l’enregistrement de l’ability ne sert pas uniquement à documenter les paramètres attendus pour un agent qui découvrirait l’ability dynamiquement : il constitue également une première barrière de validation, rejetant toute invocation dont les paramètres ne correspondent pas exactement à ce qui est attendu, avant même d’atteindre le permission_callback :

'input_schema' => array(
    'type'                 => 'object',
    'properties'           => array(
        'article_id' => array( 'type' => 'integer', 'minimum' => 1 ),
    ),
    'required'             => array( 'article_id' ),
    'additionalProperties' => false, // rejette tout paramètre non prévu
),

La ligne additionalProperties: false mérite une attention particulière : sans elle, un agent pourrait envoyer des paramètres supplémentaires non documentés, que le execute_callback pourrait, par erreur de programmation, exploiter sans qu’aucune vérification n’ait jamais été prévue pour eux.

Étape 4 : tester explicitement les invocations qui doivent échouer

Comme pour toute déclaration de permission, la vérification ne se limite pas à confirmer qu’une invocation légitime réussit. Il faut tester activement, pour chaque ability déclarée, plusieurs scénarios de rejet attendu :

• Invocation par un agent non listé dans agents_autorises, même avec un utilisateur disposant de edit_posts.
• Invocation sur un article publié depuis moins de trois ans, qui doit être rejetée malgré des permissions par ailleurs correctes.
• Invocation avec un paramètre supplémentaire non prévu dans le schéma, qui doit être rejetée avant même d’atteindre la logique métier.

wp eval '
$resultat = wp_execute_ability( "monsite/archiver-article", array(
    "article_id" => 42,
), array( "agent_id" => "agent-non-autorise" ) );
var_dump( $resultat ); // doit renvoyer une erreur de permission
'

Étape 5 : documenter les abilities exposées pour l’équipe technique

Une fois les abilities déployées, il devient utile de maintenir un inventaire lisible de toutes celles exposées par le site, avec leur niveau de risque et les agents autorisés à les invoquer, à l’image de ce qui se pratique déjà pour les scopes d’un serveur MCP :

Ability	Agents autorisés	Niveau de risque
monsite/archiver-article	agent-archivage-2025	Faible (réversible)
monsite/supprimer-utilisateur	Aucun agent, humain uniquement	Élevé (irréversible)

Une ability bien déclarée ne se contente pas de dire ce qu’elle fait, elle dit aussi, explicitement, qui a le droit de le lui demander et sous quelles conditions précises.

Ce qu’il faut retenir

L’Abilities API n’invente pas un nouveau modèle de sécurité, elle structure et rend explicite ce que des développeurs prudents faisaient déjà manuellement dans leurs routes REST personnalisées : vérifier la capacité, vérifier l’identité de l’agent invoquant, vérifier la cohérence métier de la donnée manipulée. Sa valeur ajoutée réside dans la standardisation de ces trois niveaux de vérification au sein d’un même mécanisme, documenté et découvrable par les agents eux-mêmes, ce qui facilite grandement l’audit de ce qu’un site expose réellement à l’écosystème des agents connectés.