Référence ActionContext

English version: ../../en/guides/action-context.md

Cette page décrit l'ActionContext : l'enregistrement d'une décision sur une action d'un agent, d'un outil ou d'un utilisateur qui agit par une délégation. Elle liste ses champs, les couches de la décision, et comment en obtenir et en lire un. Qui : développeurs d'agents, d'outils et de serveurs MCP, responsables de la sécurité et auditeurs.

Contrat

Le schéma est contracts/v1/action-context.schema.json (Action Context v1). Champs obligatoires : schema_version, action_id, action, execution_id, subject, decisions, requested_at. Il relie une action à l'ExecutionContext signé par context_id (le jti du jeton).

Champs

subject : principal_id et on_behalf_of obligatoires, plus root_principal_id, agent, subagent, workload, delegation_id. target : kind, ref, operation, destination, classification. decisions : allow obligatoire, plus policy_decision_id, openfga, opa, layers. requested décrit l'intention, observed ce qui a été constaté ; result vaut allowed, denied, succeeded, failed ou pending_approval ; audit_event_ids relie l'action au journal d'audit.

Couches de la décision

La réponse de POST /v1/delegations/authorize porte un verdict par couche dans layers ; allow n'est vrai que si chaque couche autorise, et une couche qui refuse donne sa reason.

Couche	Ce qu'elle vérifie
chain	la chaîne de délégation est valide : ni révoquée, ni expirée, profondeur dans les bornes
session	avec un run_id, l'exécution peut encore agir (contrôles d'état et de session)
user	l'utilisateur d'origine détient le droit
agent	le manifeste de l'agent autorise le droit
delegation	la délégation accorde le droit
resource	la ressource est dans la restriction de ressources de la délégation
audience	l'audience est autorisée par la délégation
classification	la classification des données ne dépasse pas data_classification_max
relationship	avec resource et relation, OpenFGA confirme que l'utilisateur d'origine et l'appelant détiennent tous deux la relation (échec fermé si OpenFGA ne répond pas)
policy	la politique OPA ou intégrée autorise l'action

Produire un ActionContext

POST /v1/delegations/authorize (services/control-plane/src/eai/domains/delegation/runtime.py, fonction authorize) calcule le droit effectif utilisateur ET agent ET délégation ET ressource ET relation ET politique, enregistre la décision et l'audit, puis renvoie l'ActionContext ; allow n'est vrai que si chaque couche autorise.

await client.delegations.authorize({ action: "crm.read", resource: "crm:contact:42" });

Procédures

1. Accorder une délégation. Sans délégation, la plateforme ne sait pas pour le compte de qui l'action s'exécute : la décision est refusée.

   Écran : Sécurité et gouvernance > Délégations > Nouvelle délégation. API : POST /v1/delegations avec delegate (obligatoire), plus scopes, resources, audience, data_classification_max, ttl_seconds ou expires_at, max_depth, redelegation_allowed, purpose.

   Résultat attendu : un identifiant de délégation, lisible avec GET /v1/delegations/{delegation_id}.

   En cas d'échec : 403 delegation_scope_exceeds signale que vous déléguez un droit que vous ne détenez pas.

2. Demander une décision avant d'agir. Un outil ou un serveur MCP l'appelle avant chaque action sensible, avec l'exécution ou la délégation sous laquelle il agit.

   API : POST /v1/delegations/authorize avec action (par exemple crm.read), et run_id ou delegation_id, plus scope, resource (<type>:<id>), relation, audience, data_classification.

   Résultat attendu : un ActionContext avec action_id, allow, layers, subject, delegation, decisions et decided_at.

   En cas d'échec : 403 delegation_required signale qu'aucune exécution avec délégation ni aucun delegation_id n'a été donné ; 404 delegation_not_found signale une délégation inconnue ; 422 validation_error signale une action ou une resource qui ne suit pas la forme attendue.

3. N'agir que si allow est vrai. Une couche qui refuse est un refus, jamais un avertissement : arrêtez l'action et rapportez la reason de la couche qui refuse.

   Résultat attendu : l'action s'exécute, et la décision figure au journal d'audit sous authz.authorize.

   En cas d'échec : quand allow est faux, lisez layers pour trouver la couche qui refuse.

4. Tracer l'action dans l'audit. L'événement d'audit authz.authorize enregistre l'action, le droit, la ressource, les couches et l'exécution, refus compris.

   Résultat attendu : GET /v1/audit/events liste l'événement de la décision.

   En cas d'échec : 403 forbidden signale que votre rôle ne peut pas lire le journal d'audit.

5. Révoquer au besoin. Révoquer une délégation arrête toute décision ultérieure prise sous elle.

   API : POST /v1/delegations/{delegation_id}/revoke, ou POST /v1/delegations/{delegation_id}/restrict pour la restreindre.

   Résultat attendu : la décision suivante refuse la couche chain.

   En cas d'échec : 404 delegation_not_found.

Dépannage

Statut	Code	Cause	Correction
403	delegation_required	aucune exécution avec délégation et aucun delegation_id	accordez une délégation, passez son identifiant ou l'exécution
404	delegation_not_found	délégation inconnue	vérifiez l'identifiant et le tenant
403	delegation_scope_exceeds	délégation d'un droit que vous ne détenez pas	déléguez un sous-ensemble de vos droits
403	delegation_expired	la délégation est finie	accordez une nouvelle délégation
422	validation_error	action hors de la forme domaine.verbe, ou resource hors de la forme type:id	corrigez le corps de la requête
200	allow: false	une couche refuse	lisez la reason de la couche qui refuse

Étapes suivantes

• Référence ExecutionContext
• Guide de développement de politiques : écrire la couche de politique.
• Référence API