Authentification
Chaque demande est authentifiée par une clé API espace de travail, envoyé comme jeton au porteur:
Authorization: Bearer maetra_xxxxxxxxxxxxxxxxxxxx
Les clés commencent par maetra_C'est vrai. Une clé appartient à un espace de travail et porte un ensemble fixe de champ d'applicationC'est vrai. La même clé authentifie la API REST et les Serveur MCP.
Créer une clé API (dans le tableau de bord)#
- Ouvrez le tableau de bord d'Maetra et allez à Paramètres → touches d'API.
- Cliquez sur Créer la clé API.
- Remplissez le dialogue & #160;:
- Nom de la clé — une étiquette pour la reconnaître ultérieurement, par exemple
Production FinanceAgent. - Portées d'accès — choisir Accès completou Portées personnalisées choisir par module (Discover, Comply, Govern, Secure, Audit, Task Guard). Accorder le moins d'un besoin clé — voir Portée ci-dessous.
- Restrictions en matière de propriété intellectuelle (facultatif) — une ou plusieurs plages IP/CIDR dont la clé peut être utilisée, par exemple:
192.168.1.0/24.
- Nom de la clé — une étiquette pour la reconnaître ultérieurement, par exemple
- Cliquez sur CréerC'est vrai. La clé complète est affichée une fois — touché Copier la clé, rangez-le dans un gestionnaire secret, alors J'ai sauvé ma clé..
Important Maetra ne stocke qu'un hachage de la clé et ne peut plus la montrer. Si une clé est perdue ou divulguée, la révoquer et en créer un nouveau - vous ne pouvez pas le récupérer.
Portée#
Les champs d'application sont vérifiés par demande. Un appel revient 403 Forbidden si la clé est valide mais n'a pas la portée requise.
| Portée | Subventions |
|---|---|
govern:checkpoints:write | Créer des points de contrôle |
govern:checkpoints:read | Points de contrôle de la lecture / à longue portée |
govern:policies:read | Énumérer les politiques actives |
secure:scan:write | Contenu de l'analyse |
secure:rules:read | Liste des règles Secure |
secure:rules:write | Créer et mettre à jour les règles Secure |
secure:incidents:read | Liste des incidents |
discover:agents:read | Liste des agents enregistrés |
task_guard:tasks:write | Démarrer, mettre à jour, arrêter, reprendre, annuler et terminer les tâches d'Task Guard |
task_guard:tasks:read | Récupérer le contexte actif de la tâche Task Guard |
task_guard:checks:write | Vérifier l'alignement de l'action et expliquer les relations de tâches |
task_guard:effects:write | Signaler et comparer les effets réels de l'action |
task_guard:confirmations:write | Soumettre des événements d'hôte de confiance et des confirmations de portée |
Cartes sauvages
Une clé peut contenir des champs wildcard : * (tout), ou un préfixe de module comme govern:* / secure:* / discover:* / task_guard:*C'est vrai. Le tableau de bord Accès complet Aides *; choisir un module entier sous Portées personnalisées octroie ce module *.
Remarque
task_guard:confirmations:writeest nécessaire mais ne suffit pas pour les événements d'accueil de confiance et les confirmations de portée en ligne. La clé API doit également être marquée comme un justificatif de confirmation Task Guard de confiance pour l'espace de travail.
Vérifiez une clé#
Utilisation GET /v1/ping pour confirmer une clé est valide et voir ses champs d'application:
curl "https://api.maetra.io/v1/ping" \
-H "Authorization: Bearer $MAETRA_API_KEY"
{ "ok": true, "workspace_id": "ws_3Nf9k2", "scopes": ["govern:checkpoints:write"] }
Récupérer une clé#
Récupérer une clé de Paramètres → touches d'API (le menu des actions de la ligne). Révocation immédiate — nouvelles demandes de retour 401 UnauthorizedC'est vrai. La révocation d'une clé n'affecte jamais les autres.
Voir Erreurs et limites de taux pour le format d'erreur complet.