Clés API

Une clé API autorise un système externe, par exemple votre ERP, à utiliser l’API REST v1 d’exoCortex : ouvrir des tickets, lire leur statut et ajouter des commentaires. Chaque clé appartient à un tenant et ne voit que les tickets de ce tenant.

Créer une clé

1. Dans exoCortex Core, ouvrez Integrations → API keys. Un rôle administratif est nécessaire, par exemple it_admin ou integration_admin.
2. Donnez à la clé un nom qui indique qui l’utilise, par exemple « Connecteur ERP ».
3. Choisissez les scopes, c’est-à-dire ce que la clé peut faire (voir ci-dessous).
4. Copiez la clé complète et enregistrez-la dans le gestionnaire de secrets du système qui l’utilisera. exoCortex ne l’affiche qu’une seule fois et n’en conserve qu’une empreinte : si vous la perdez, créez une nouvelle clé.

La clé a la forme nhk.<keyid>.<secret>. Le keyid identifie la clé dans la liste ; le secret n’est connu que de vous.

Scopes

Scope	Ce qu’il permet
tickets:create	Ouvrir des tickets
tickets:read	Lire le statut d’un ticket
tickets:comment	Ajouter des commentaires à un ticket
tickets:*	Toutes les opérations sur les tickets
*	Tout ce que l’API v1 permet

N’attribuez à chaque clé que les scopes dont elle a besoin. Une clé sans scope a un accès complet à l’API v1 : c’est autorisé, mais déconseillé.

Utiliser la clé

Envoyez la clé dans l’en-tête Authorization de chaque requête :

POST /api/v1/tickets HTTP/1.1
Host: exocortex-api.ai-exo-cortex.com
Authorization: Bearer nhk.9f2c4e1a7b3d.…
Content-Type: application/json
Idempotency-Key: 6b1f0c4e-2a7d-4b39-9e51-8c3d2f7a1b60

{ "subject": "Payment gateway returns HTTP 502", "priority": "High" }

Vous pouvez aussi utiliser l’en-tête X-NH-API-Key. Vous n’indiquez pas le tenant : exoCortex le déduit de la clé.

Utilisez toujours Idempotency-Key lorsque vous ouvrez un ticket : si vous répétez la requête avec la même clé d’idempotence, vous recevez le ticket déjà créé au lieu d’un doublon.

Limites de fréquence

Chaque clé a une limite de requêtes : la valeur par défaut est de 600 requêtes toutes les 60 secondes. Chaque réponse indique où vous en êtes :

En-tête	Signification
RateLimit-Limit	Requêtes autorisées dans la fenêtre
RateLimit-Remaining	Requêtes encore disponibles
RateLimit-Reset	Secondes avant la nouvelle fenêtre
Retry-After	Uniquement avec la réponse 429 : secondes à attendre avant de réessayer

Erreurs

Les erreurs de l’API v1 renvoient un JSON avec ok: false, un message lisible dans error et un code stable dans code. Fondez la logique de votre client sur le code, pas sur le message.

code	Statut HTTP	Que faire
missing_api_key	401	Ajoutez l’en-tête Authorization
invalid_api_key	401	Vérifiez la clé : elle peut être erronée ou révoquée
insufficient_scope	403	Ajoutez à la clé le scope indiqué dans required_scope
api_key_disabled	403	La clé est désactivée : utilisez une clé active
validation_error	400	Corrigez le champ indiqué dans field
not_found	404	Le ticket n’existe pas ou n’appartient pas au tenant de la clé
rate_limited	429	Attendez le nombre de secondes indiqué dans Retry-After
ingest_failed	500	Réessayez avec la même Idempotency-Key

exoCortex peut ajouter de nouveaux codes : si vous en recevez un que vous ne connaissez pas, décidez en fonction du statut HTTP.

Révoquer une clé

Depuis Integrations → API keys, révoquez une clé lorsqu’un système ne l’utilise plus ou si vous pensez qu’elle a été exposée. La révocation est immédiate. La liste affiche aussi la dernière utilisation de chaque clé : cela vous aide à repérer les clés inactives.

Clés nh_… dépréciées

Les clés à l’ancien format nh_… fonctionnent jusqu’au 30 juin 2027. Les réponses à ces clés contiennent les en-têtes Deprecation et Sunset. Pour migrer, créez une clé nhk. avec les scopes nécessaires, mettez à jour le système qui l’utilise, puis révoquez l’ancienne clé.