Jetons d'API

Les jetons d'API offrent à vos systèmes externes et à vos scripts un accès sécurisé et à portée limitée à la plateforme Mirox sans partager vos identifiants de connexion. Vous les créez dans votre profil, accordez à chacun uniquement les autorisations dont il a besoin, et vous pouvez en révoquer ou en faire tourner n'importe lequel à tout moment.

Aperçu

Contrairement à votre nom d'utilisateur et à votre mot de passe, un jeton d'API :

• Porte un groupe d'autorisations spécifique qui limite ce à quoi il peut accéder
• Dispose d'une date d'expiration configurable (un an par défaut, cinq ans au maximum)
• Peut être renouvelé avec un nouveau secret ou révoqué individuellement, sans toucher à votre compte ni à vos autres jetons
• Enregistre son propre historique d'utilisation (date de dernière utilisation, adresse IP source, emplacement, navigateur et système d'exploitation) afin que vous puissiez voir le comportement de chaque intégration

Vous pouvez détenir jusqu'à 64 jetons à la fois.

Créer des jetons d'API

Les jetons d'API peuvent être créés via l'interface web Mirox :

1. Connectez-vous à votre compte Mirox
2. Ouvrez le menu Profil (en haut à droite) et choisissez Profil
3. Sélectionnez l'onglet « Jetons d'API »
4. Cliquez sur « Créer un nouveau jeton »
5. Configurez les paramètres du jeton :
   • Nom (libellé descriptif du jeton)
   • Date d'expiration (1 an par défaut si non spécifiée, 5 ans au maximum)
   • Portée des autorisations (ressources et actions spécifiques auxquelles le jeton peut accéder)
6. Cliquez sur « Générer le jeton »

Ouvrir dans Mirox : Profil ▸ Jetons d'API — gérez vos jetons depuis le menu Profil ▸ Profil, puis l'onglet « Jetons d'API ».

Bonnes pratiques de sécurité des jetons

Lorsque vous travaillez avec des jetons d'API :

1. Stockez-les en lieu sûr — Traitez les jetons comme des mots de passe ; ne les codez jamais en dur dans les applications
2. Utilisez des variables d'environnement — Stockez les jetons dans des variables d'environnement ou des coffres d'identifiants sécurisés
3. Limitez la portée — Créez des jetons avec le minimum d'autorisations nécessaires à l'intégration
4. Définissez des expirations appropriées — Utilisez des durées d'expiration plus courtes pour les intégrations temporaires
5. Planifiez la rotation — Définissez des rappels d'agenda avant l'expiration du jeton afin d'assurer la continuité du service
6. Faites des rotations régulières — Utilisez l'action Renouveler intégrée pour faire tourner périodiquement le secret d'un jeton avant son expiration, en particulier pour les systèmes de production
7. Révoquez les jetons inutilisés — Révoquez immédiatement les jetons qui ne sont plus nécessaires
8. Surveillez l'utilisation — Auditez régulièrement l'activité des jetons via l'interface Mirox

Utiliser les jetons d'API

Les jetons d'API sont utilisés dans les requêtes HTTP en tant que jeton Bearer dans l'en-tête Authorization :

Authorization: Bearer your-api-token

Les exemples suivants nécessitent un jeton du groupe d'autorisations Full Access.

Exemple de requête HTTP

GET /api/v1/park HTTP/1.1
Host: service.mirox.io
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Content-Type: application/json

Exemple Curl

curl -X GET \
  https://service.mirox.io/api/v1/park \
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...' \
  -H 'Content-Type: application/json'

Autorisations des jetons

Les jetons d'API sont soumis à la couche d'autorisations des jetons d'API de la plateforme Mirox. Points clés concernant les autorisations des jetons :

• Les jetons héritent des autorisations de l'utilisateur qui les a créés (jamais davantage)
• Les autorisations peuvent être restreintes davantage par fonctionnalité
• Les jetons opèrent au sein du même modèle d'autorisations hiérarchique que les comptes utilisateurs
• Tous les contrôles de sécurité de la plateforme s'appliquent à l'accès par jeton

Pour des informations détaillées sur la place des jetons d'API dans l'architecture globale des autorisations, consultez la documentation du système d'autorisations.

Groupes d'autorisations

Lorsque vous créez un jeton, vous choisissez l'un des trois groupes d'autorisations qui délimitent ce à quoi il peut accéder :

• Full Access — accorde au jeton les mêmes autorisations que votre compte utilisateur, dans la limite de votre portée. Tout service l'utilisant peut agir en votre nom sur l'ensemble de la plateforme ; ne choisissez donc cette option que lorsqu'une intégration a réellement besoin d'un accès étendu.
• Reporting — restreint le jeton aux fonctionnalités de reporting : génération de rapports et exportation de données.
• Timeseries Database — restreint le jeton aux points d'accès de requête de séries temporelles, pour récupérer des données de mesure de façon programmatique (par exemple avec MiroxQL).

Choisissez le groupe le plus restreint qui couvre votre intégration. Un jeton Reporting ou Timeseries Database ne peut accéder à rien en dehors de sa portée, ce qui limite l'étendue des dégâts en cas de fuite.

Gestion du cycle de vie des jetons

Surveiller l'utilisation des jetons

Suivez l'activité des jetons d'API via :

1. La section « Jetons d'API » de votre profil
2. Les journaux d'audit qui indiquent quand et comment chaque jeton a été utilisé

Renouveler les jetons

Le renouvellement remplace le secret d'un jeton sans changer son nom, son groupe d'autorisations ni sa place dans votre liste de jetons. Cela vous permet de faire tourner une clé selon un calendrier, ou de réagir à une fuite présumée, tout en conservant la même entrée de jeton dans la configuration de vos intégrations.

Pour renouveler un jeton :

1. Accédez à la section « Jetons d'API » de votre profil
2. Trouvez le jeton dans la liste et choisissez « Renouveler »
3. Copiez le nouveau secret immédiatement — il n'est affiché qu'une seule fois
4. Mettez à jour le secret dans l'intégration qui l'utilise

Le renouvellement émet un nouveau secret, réinitialise la fenêtre d'expiration et efface l'historique d'utilisation enregistré du jeton. L'ancien secret cesse immédiatement de fonctionner ; mettez donc vos intégrations à jour dans le cadre du renouvellement.

Révoquer les jetons

Pour révoquer un jeton :

1. Accédez à la section « Jetons d'API » de votre profil
2. Trouvez le jeton dans la liste
3. Cliquez sur « Révoquer »
4. Confirmez l'action

La révocation prend effet immédiatement, et toute requête ultérieure utilisant le jeton échouera.

Limitations d'utilisation

Les jetons d'API sont soumis aux mêmes limites de débit que les comptes utilisateurs normaux. Pour plus de détails sur ces limitations, consultez la section Limitation de débit de la documentation sur les concepts d'authentification.

Dépannage

Problèmes courants liés aux jetons et solutions :

Exemples de code

Pour du code fonctionnel utilisant un jeton d'API de bout en bout, consultez :

• Générateur de rapports externe — un script Python qui s'authentifie avec un jeton et récupère une exportation de métriques
• MiroxQL — le langage de requête pour récupérer des données de séries temporelles avec un jeton Timeseries Database

Fonctionnalités associées

• Aperçu de l'API — le point d'entrée de l'API REST Mirox et sa documentation en ligne
• Système d'autorisations — comment les groupes d'autorisations de jeton s'intègrent au modèle de rôles de la plateforme
• Authentification — les sessions, la connexion à deux facteurs et les limites de débit qui s'appliquent également aux jetons
• MiroxQL — interrogez des données de séries temporelles de façon programmatique avec un jeton Timeseries Database
• API d'exportation de métriques — exportez des données de mesure et des rapports avec un jeton Reporting