Jetons API personnels
Les jetons d'API personnels permettent à un utilisateur CMS connecté de déléguer le travail à un outil d'IA ou d'opérateur sans partager de mot de passe ni accorder d'autorité à l'échelle de l'installation. L'IA agit en tant qu'utilisateur : chaque demande est limitée par les paramètres de jeton et de l'accès CMS actuel de l'utilisateur.
Jetons personnels et système
| Type de jeton | Créé à partir de | Propriétaire prévu | Autorité |
|---|---|---|---|
| Jeton API personnel | Profil → Jetons API personnels | Éditeur, Site admin ou Super admin | Le contenu et le site fonctionnent dans le cadre du rôle actif du propriétaire et des sites sélectionnés |
| Jeton API système | Système → Jetons API | Super admin | Automatisation fiable au niveau de l'installation avec des fonctionnalités explicitement sélectionnées |
Les jetons personnels excluent délibérément les mises à jour du système au niveau de l'installation, les sauvegardes, la maintenance, les plugins, les applications intégrées, les domaines, les ressources physiques du site/page et le rendu administrateur. Un super administrateur qui doit automatiser ces opérations doit créer un jeton d’API système distinct. Cela empêche un assistant personnel de devenir silencieusement un opérateur d'installation.
Règle d'autorisation effective
A ne peut effectuer une opération que lorsque toutes ces vérifications réussissent :
- Le token est actif et n'a pas expiré.
- Son propriétaire est toujours un utilisateur actif du CMS.
- La capacité demandée est sélectionnée sur le token.
- Le rôle actuel du propriétaire permet toujours cette capacité.
- Le site cible est sélectionné sur le token et reste accessible au propriétaire.
- L'état actuel du flux de travail de la page permet au propriétaire d'effectuer la modification demandée.
- La demande provient d'un réseau autorisé, lorsqu'une liste blanche IP est configurée.
- Les limites de requêtes spécifiques au jeton et à l'échelle de l'installation n'ont pas été dépassées.
La modification du rôle d'un utilisateur, des attributions de site ou de l'état actif prend effet à la prochaine requête API. Un jeton ne préserve jamais l'autorité que son propriétaire a perdue.
Matrice de rôles
| Jeton d'éditeur | Jeton Site admin | Jeton personnel Super admin | Jeton système | |
|---|---|---|---|---|
| Lire le contenu du site attribué | Oui | Oui | Tous les sites | Si accordé |
| Créer et modifier un brouillon de contenu | Oui | Oui | Tous les sites | Si accordé |
| Publier ou archiver | Non | Si accordé | Si accordé | Si accordé |
| Paramètres de présentation du site sécurisé | Non | Si accordé | Si accordé | Si accordé |
| Navigation, Shared Slots, médias et engagement | Dans les sites sélectionnés et attribués, si accordé | Dans les sites sélectionnés et attribués, si accordé | Dans les sites sélectionnés, si accordé | Si accordé |
| Utilisateurs, mises à jour, sauvegardes, maintenance, plugins, applications, domaines, actifs physiques | Non | Non | Non | Uniquement avec la capacité correspondante |
Le formulaire de jeton affiche uniquement les capacités que l'utilisateur actuel peut déléguer. La sélection d'une capacité constitue une limite supérieure et non un moyen de contourner le rôle.
Créer un jeton
- Ouvrez Profile et sélectionnez Gérer les jetons API.
- Entrez un nom qui identifie le client ou le travail.
- Sélectionnez les sites que l'IA peut atteindre.
- Sélectionnez uniquement les capacités dont le travail a besoin.
- Choisissez une période d'expiration.
- Définissez la limite de demande à côté du contrôle d'expiration, en dessous de la sélection du site autorisé. Configurez éventuellement une liste d'autorisation IP sous les contrôles réseau.
- Sélectionner Créer un jeton.
- Copiez le jeton immédiatement. Sa valeur simple n'est affichée qu'une seule fois.
Le panneau de réussite fournit l'URL de base de l'API, un exemple de variable d'environnement et une invite de configuration de l'IA prête à copier. Donnez le secret uniquement à l'outil prévu et stockez-le dans le magasin secret de cet outil.
Modifier, réviser, révoquer ou supprimer
- Edit modifie le nom, les sites sélectionnés, les capacités, l'expiration renouvelée, la liste d'autorisation IP et le plafond de demande sans révéler ni remplacer le secret.
- Activity affiche les dix dernières requêtes : résultat, heure, méthode, chemin sans chaîne de requête, itinéraire, capacité requise, IP et un agent utilisateur raccourci.
- Revoke empêche immédiatement toute authentification ultérieure tout en conservant le jeton et l'historique des activités.
- Delete supprime définitivement le jeton et son historique d'activité.
RLes corps de requête et de réponse, les chaînes de requête, les valeurs de support, les hachages de jetons et les aperçus de jetons ne sont jamais stockés dans les lignes d'activité.
Contrôles réseau
La liste blanche accepte une adresse IPv4/IPv6 exacte ou un réseau CIDR par ligne, par exemple :
203.0.113.10
198.51.100.0/24
2001:db8::/32Laissez la liste vide pour autoriser n'importe quel réseau. Choisissez un plafond spécifique au jeton de 30, 60, 120 ou 300 requêtes par minute. Les jetons existants sans plafond stocké utilisent 60 requêtes par minute. La limitation de l'API à l'échelle de l'installation s'applique toujours, la limite effective est donc la limite applicable la plus basse.
Proxy inverses et CDN
Les vérifications réseau utilisent l'adresse IP client résolue par Laravel. Lorsque l'hôte se trouve derrière un équilibreur de charge, un proxy inverse ou un CDN, configurez la gestion du proxy de confiance de Laravel pour les adresses proxy réelles et les en-têtes transférés. Vérifiez l'adresse résolue avant d'activer une liste blanche restrictive. Ne faites pas confiance aux en-têtes transmis par des clients Internet arbitraires ; sinon, un appelant peut usurper l'adresse utilisée par la stratégie.
Connecter une IA
Configurez les valeurs générées dans le magasin de secrets de confiance de l'outil :
WEBBLOCKS_CMS_API_URL=https://example.com/webadmin/api
WEBBLOCKS_CMS_API_TOKEN=...L'outil doit d'abord appeler GET /webadmin/api. La découverte authentifiée renvoie ses capacités, sa politique de réseau personnel, ses liens OpenAPI et guides, ainsi que les prochaines étapes recommandées. Il doit valider les plans de contenu avant de les appliquer et demander l'approbation explicite de l'utilisateur avant toute opération de publication ou de destruction.
Contrat d'erreur
| HTTP | Codes | Signification |
|---|---|---|
| 401 | invalid_internal_api_token | Le jeton est manquant, invalide, révoqué, expiré ou n'est plus soutenu par un utilisateur CMS actif |
| 403 | missing_internal_api_capability | Le jeton ne possède actuellement pas la capacité requise |
| 403 | delegated_site_access_denied | La ressource sélectionnée ou le site soumis se trouve en dehors de la portée active du propriétaire du jeton. |
| 403 | delegated_workflow_access_denied | Le propriétaire ne peut pas modifier la page dans son état de flux de travail actuel |
| 403 | delegated_operation_denied | L'opération est au niveau de l'installation et ne peut pas utiliser de jeton personnel |
| 403 | delegated_network_access_denied | L'adresse IP du client résolu se trouve en dehors de la liste autorisée des jetons. |
| 429 | personal_api_token_rate_limit_exceeded | Le plafond de demande spécifique au jeton a été atteint ; honneur Retry-After |
| 422 | Code de validation spécifique au point de terminaison | La requête est authentifiée mais sa charge utile ou sa transition d'état n'est pas valide |
AToutes les erreurs d'API sont au format JSON et incluent des liens de découverte publics lorsqu'ils sont disponibles.
Pratique recommandée
- Créez un jeton par tâche d'IA, d'intégration ou limitée.
- Donnez-lui le moins de sites et de fonctionnalités dont il a besoin.
- Préférer des délais de péremption courts et renouveler délibérément.
- Utilisez une liste autorisée d'adresses IP de sortie stable lorsque la plateforme AI en fournit une.
- Rexaminer l'activité récente après la configuration initiale et après un travail sensible.
- Révoquer immédiatement si un secret peut avoir été révélé.
- Ne collez jamais de jetons dans des tickets, des journaux, des captures d'écran, un contrôle de code source ou des invites susceptibles d'être conservés par des services non liés.
Voir Internal Content API, Utilisateurs et autorisations et Security pour l'API, le rôle et le déploiement sous-jacents limites.