Authentification

Les programmes s’authentifient avec des clés API. Une clé agit comme le membre qui l’a créée, limitée aux permissions que vous accordez à la clé. Il n’y a pas d’échange de jeton : la clé elle-même est l’identifiant, envoyé à chaque appel.

Les clés API sont gérées par les administrateurs dans API Keys (dans la partie Developer du menu). La création de clés nécessite une offre incluant les clés API.

Créer une clé

1. Ouvrez API Keys et sélectionnez New API Key.
2. Saisissez un Name (100 caractères maximum) et, facultativement, une Description (500 caractères maximum).
3. Sous Module permissions, choisissez ce que la clé peut faire, un module à la fois. Chaque module propose un préréglage Read only ; vous pouvez aussi cocher des permissions individuelles. Utilisez Search modules or permissions… pour en trouver une. Le sélecteur ne liste que les permissions que vous détenez vous-même : « La clé peut faire au plus ce que vous pouvez faire. Si vos propres droits se réduisent plus tard, la clé les perd aussi. »
4. Définissez Expires on. La valeur par défaut est 90 jours à partir d’aujourd’hui, un an au maximum (« 90 days by default, at most a year. »).
5. Remplissez éventuellement IP allowlist : un sous-réseau par ligne, par exemple 10.0.0.0/8 ou 203.0.113.7/32. Vide signifie toute adresse autorisée par votre organisation.
6. Laissez Integration scopes (advanced) vide, sauf si la documentation d’une intégration en demande un (par exemple la provisioning SCIM).
7. Sélectionnez Create Key et copiez la clé immédiatement.

Si vous utilisez l’authentification à deux facteurs ou une passkey, Hermetry vous demande de la confirmer avant la création de la clé. Une clé ne peut pas être créée pendant que vous usurpez l’identité d’un membre.

Format de la clé

sk_live_<first 8 characters of the organisation id>_<48 random hexadecimal characters>

Les clés live appartiennent au service de production, les clés test aux installations de test, afin que les deux ne puissent pas être confondues.

Utiliser une clé

Envoyez la clé dans l’en-tête Authorization à chaque appel :

curl "https://<your host>/tenant/<tenantId>/api/iot/devices" \
  -H "Authorization: Bearer sk_live_…"

• Une requête avec une clé API n’est évaluée que selon cette clé. Un cookie de navigateur sur la même requête est ignoré.
• Les clés ne fonctionnent que sur les chemins de votre organisation (/tenant/<tenantId>/api/...). L’organisation de la clé doit correspondre au tenantId du chemin.
• Une clé ne fonctionne jamais sur les routes de la plateforme, du compte ou de connexion.

Ce qu’une clé peut faire

À chaque appel, toutes ces conditions doivent être remplies :

1. La clé détient la permission requise par la route.
2. Le module de la permission est activé pour votre organisation.
3. Le membre qui a créé la clé détient la permission maintenant : son rôle, ses groupes et vos politiques d’accès sont pris en compte.
4. Le membre est toujours un membre actif et l’organisation est active.

Une clé agit avec le rôle Admin au plus, même si un Owner l’a créée. Ainsi, une clé ne peut jamais détenir les permissions réservées aux Owners (par exemple les commandes brutes des appareils, les clés de signature du firmware, les réglages dangereux des appareils, la rotation d’un secret de webhook), ni les permissions des modules d’identité et d’accès (connexion, comptes, clés API, membres, sessions). Une clé ne peut donc pas créer ni faire tourner des clés.

Clés de service

Une clé cesse normalement de fonctionner lorsque son créateur quitte l’organisation. Un Owner peut ouvrir la clé et sélectionner Mark as service key : elle continue alors de fonctionner après le départ de son créateur (« Yes: survives its creator ») et agit comme l’Owner qui l’a marquée.

Réseaux autorisés

La liste IP d’une clé contient jusqu’à 100 sous-réseaux au format CIDR ; une adresse unique s’écrit /32. Les appels provenant d’ailleurs sont refusés avec 403 « Cette clé API ne peut pas être utilisée depuis l’adresse IP actuelle. » Une clé sans liste propre utilise la liste par défaut de l’organisation (voir Settings ci-dessous). Les listes d’autorisation et de refus IP de votre organisation pour la connexion s’appliquent aussi aux clés.

Expiration

Chaque clé expire. La valeur par défaut est 90 jours ; la date la plus lointaine est à 365 jours, ou moins si votre organisation fixe un maximum inférieur. Les clés expirées cessent de fonctionner d’elles-mêmes. Un administrateur peut aussi balayer les clés expirées (POST /api/api-keys/sweep-expired) pour les marquer inactives et envoyer un événement de webhook api_key.expired par clé.

Faire tourner, désactiver et révoquer

Ouvrez une clé pour voir son Identity, son Usage (dernière utilisation, dernière adresse IP utilisée, nombre total de vérifications), ses Module permissions et son Rotation history.

• Rotate key crée une clé successeur avec les mêmes permissions, scopes, liste de réseaux et environnement. Définissez la Grace window (days) : l’ancienne clé continue de fonctionner jusqu’à son terme. « 0 révoque immédiatement l’ancienne clé. » Copiez le nouveau secret tout de suite.
• Deactivate arrête une clé jusqu’à ce que vous la réactiviez avec Activate. Une clé remplacée ne peut pas être réactivée : « Une clé remplacée ne peut pas être réactivée ; utilisez son successeur. »
• Revoke supprime la clé : « Toutes les intégrations utilisant cette clé cesseront immédiatement de fonctionner. Cette action est irréversible. »
• Edit modifie les permissions de modules de la clé. Vous pouvez retirer n’importe quelle permission, et n’en ajouter que celles que vous détenez. Les scopes d’intégration ne peuvent être que restreints.

En cas d’incident, un administrateur peut révoquer en une seule étape toutes les clés actives de l’organisation.

{
    "graceSeconds": 86400
}

curl -X POST 'https://<your-host>/tenant/{tenantId}/api/api-keys/{apiKeyId}/rotate' \
  -H 'Content-Type: application/json' \
  -d '{"graceSeconds":86400}'

{
    "key": {
        "name": "Plant ERP",
        "…": "…"
    },
    "rawKey": "sk_live_…"
}

{
    "message": "Only an active, unexpired key that has not been rotated yet can be rotated.",
    "code": "CONFLICT"
}

Gérer les clés via HTTP

Les clés sont gérées par un administrateur connecté. Une clé API ne peut pas créer, modifier ni faire tourner des clés.

{
    "name": "Plant ERP",
    "permissions": [
        "iot_device.devices.read",
        "telemetry.read"
    ],
    "ipAllowlist": [
        "203.0.113.0/24"
    ]
}

curl -X POST 'https://<your-host>/tenant/{tenantId}/api/api-keys' \
  -H 'Content-Type: application/json' \
  -d '{"name":"Plant ERP","permissions":["iot_device.devices.read","telemetry.read"],"ipAllowlist":["203.0.113.0/24"]}'

{
    "key": {
        "name": "Plant ERP",
        "…": "…"
    },
    "rawKey": "sk_live_…"
}

{
    "message": "Select at least one module permission or integration scope."
}

{
    "message": "An API key can only receive permissions you hold yourself."
}

{
    "message": "The expiry date must be in the future."
}

Vérifier une clé

{
    "scope": "read"
}

curl -X POST 'https://<your-host>/tenant/{tenantId}/api/api-keys/verify' \
  -H 'Content-Type: application/json' \
  -d '{"scope":"read"}'

{
    "valid": true,
    "key": {
        "name": "Plant ERP",
        "…": "…"
    }
}

{
    "valid": false,
    "message": "scope must be a string"
}

{
    "valid": false,
    "message": "Invalid or expired API key."
}

{
    "valid": false,
    "message": "Too many requests."
}

Paramètres

Les administrateurs définissent la politique de clés de l’organisation dans API Keys > paramètres (le bouton en forme d’engrenage) :

Les autres limites applicables aux clés sont décrites dans Errors and rate limits.

Surveillance des clés

• Chaque clé enregistre quand et depuis quelle adresse elle a été utilisée en dernier.
• Une clé inutilisée pendant 14 jours puis utilisée depuis une nouvelle adresse déclenche un événement d’audit (« A dormant API key was used from a new address »), au plus une fois par clé et par adresse et par heure.
• Chaque appel refusé d’une clé est enregistré dans le journal d’audit.
• Les webhooks peuvent vous informer sur les clés : api_key.created, api_key.updated, api_key.rotated, api_key.deleted, api_key.expired.

Consultez API key hardening pour une liste de contrôle.