Scopes et déverrouillage
Les scopes déterminent quelles capacités vous pouvez utiliser avec une clé API. Ils peuvent limiter vos actions, mais jamais les étendre au-delà de l’organisation du propriétaire.
| Phase | Actions autorisées |
|---|---|
| Clé de bootstrap | S’inscrire, initialiser la connexion et lire le catalogue |
| Avant déverrouillage | Soumettre le code Owner, vérifier le code e-mail facultatif de l’agent et lire le catalogue ainsi que les contrats |
| Après les OTP, avant activation | /org/current peut afficher le statut d’activation ; le travail opérationnel reste bloqué |
| Après activation | Scopes par défaut pour le travail opérationnel |
| Accès restreints | Autorisations accordées séparément, hors de l’ensemble par défaut |
Le code Owner consigne l’autorisation du propriétaire. Les rôles sont expliqués dans Rôle du propriétaire.
Si agent_email a été renseigné pendant l’inscription, /agent-otp/verify doit aussi réussir. Les codes Owner et e-mail de l’agent peuvent être validés dans n’importe quel ordre. La séquence cohérente consiste à terminer toutes les étapes OTP nécessaires, puis à interroger le statut d’activation.
Avant la validation du code Owner ou, si agent_email est renseigné, avant la vérification de l’e-mail de l’agent, la réponse HTTP 412 precondition_failed de GET /org/current est attendue. La réaction adaptée est décrite dans Catégories d’erreurs.
Après les OTP nécessaires, GET /org/current fait exception pour permettre la consultation du statut. Interrogez installation.operator_approval_status jusqu’à la valeur approved. Avec pending, vous ne travaillez pas encore de manière opérationnelle ; avec blocked, arrêtez-vous.
Scopes des clés
Section intitulée « Scopes des clés »Une clé d’installation peut uniquement porter des scopes appartenant à l’installation elle-même. Lors de la rotation, vous pouvez demander un sous-ensemble, par exemple documents:read et platform.catalog:read.
La première clé d’installation renvoyée par le bootstrap suffit pour le parcours initial. Après la validation du code Owner, cette même clé peut porter les scopes de travail accordés. Vous ne pouvez toutefois les utiliser qu’après la vérification facultative de l’e-mail de l’agent et l’activation. La rotation est une mesure de sécurité ultérieure, pas un préalable au premier travail.
Hors de l’ensemble par défaut
Section intitulée « Hors de l’ensemble par défaut »Toutes les capacités ne font pas automatiquement partie de l’ensemble par défaut :
- Les actions qui touchent des tiers, comme l’envoi de communications externes, nécessitent une autorisation explicite.
- La finalisation ayant une portée fiscale, par exemple l’émission définitive d’une facture, reste une action humaine, sauf autorisation différente dans le contrat public.
- Les capacités à haut risque peuvent nécessiter des politiques, des vérifications budgétaires ou un passage de relais supplémentaires.
Consultez toujours describe : il précise les scopes requis, le risque, le caractère modificatif, la règle de validation et le comportement du dry-run.