Version: 1.0.0

Authentification et clés API

L'API Scan Cert-IX utilise des clés API pour l'accès programmatique. Les clés API offrent des portées granulaires, des restrictions par type d'analyse, des limites de débit par clé, un allowlisting IP, une expiration automatique et une rotation sans interruption.

Méthodes d'authentification

Méthode	Cas d'utilisation	En-tête
Clé API	Accès programmatique (scripts, CI/CD, intégrations)	`X-API-Key`
JWT	Opérations du tableau de bord (gestion des clés API)	`Authorization: Bearer <token>`

Cette page couvre l'authentification par clé API. L'authentification JWT est gérée automatiquement par le tableau de bord Cert-IX.

Format des clés API

Les clés API Cert-IX suivent un format déterministe pour une identification facile :

cix_sk_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Segment	Description
`cix_`	Préfixe de la plateforme Cert-IX
`sk_`	Identifiant de type clé secrète
`XXX...`	Chaîne cryptographique aléatoire de 40 caractères

Sécurité

Les clés API sont hachées avec SHA-256 avant stockage. La clé brute est affichée une seule fois à la création. Cert-IX ne peut pas récupérer votre clé en cas de perte — vous devez effectuer une rotation.

Transmettre votre clé API

Incluez votre clé API dans l'en-tête X-API-Key à chaque requête :

curl -X GET https://api.cert-ix.com/scan-api/api/v1/scans \
  -H "X-API-Key: cix_sk_votre_cle_api_ici"

Ne transmettez jamais les clés API dans les paramètres d'URL

Les chaînes de requête peuvent être enregistrées dans les journaux d'accès serveur, l'historique du navigateur et les caches proxy.

Créer une clé API

Les clés API sont créées via le tableau de bord Cert-IX (authentification JWT).

Endpoint

POST /api/v1/api-keys

Corps de la requête

{
  "name": "Pipeline CI/CD - Production",
  "description": "Utilisée par GitHub Actions pour les analyses de vulnérabilités nocturnes",
  "scopes": [
    "scans:create",
    "scans:read",
    "scans:list",
    "results:read",
    "webhooks:read"
  ],
  "allowedScanTypes": ["nmap", "nuclei", "trivy", "zap"],
  "allowedIpAddresses": ["203.0.113.50", "198.51.100.0/24"],
  "rateLimitPerMinute": 30,
  "rateLimitPerHour": 500,
  "rateLimitPerDay": 5000,
  "expiresInDays": 90
}

Paramètres de la requête

Champ	Type	Requis	Description
`name`	string	Oui	Nom lisible de la clé (max 255 caractères)
`description`	string	Non	Description d'utilisation optionnelle
`scopes`	string[]	Non	Portées de permission (par défaut : toutes les portées)
`allowedScanTypes`	string[]	Non	Moteurs d'analyse autorisés (par défaut : tous)
`allowedIpAddresses`	string[]	Non	Plages IP/CIDR sources autorisées
`rateLimitPerMinute`	integer	Non	Requêtes max par minute
`rateLimitPerHour`	integer	Non	Requêtes max par heure
`rateLimitPerDay`	integer	Non	Requêtes max par jour
`expiresInDays`	integer	Non	Expiration en jours (`0` ou `null` = pas d'expiration)

Réponse (201 Created)

{
  "success": true,
  "data": {
    "apiKey": {
      "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "name": "Pipeline CI/CD - Production",
      "keyPrefix": "cix_sk_001e3c",
      "scopes": ["scans:create", "scans:read", "scans:list", "results:read", "webhooks:read"],
      "allowedScanTypes": ["nmap", "nuclei", "trivy", "zap"],
      "status": "active",
      "expiresAt": "2026-06-04T10:00:00Z",
      "createdAt": "2026-03-06T10:00:00Z"
    },
    "rawKey": "cix_sk_001e3c2d92ffb23344a943df2b6a001fb1028d002"
  }
}

Critique

Le champ rawKey est retourné uniquement à la création. Copiez-le immédiatement et stockez-le dans un coffre-fort sécurisé (ex. : HashiCorp Vault, AWS Secrets Manager, ou le magasin de secrets de votre CI/CD).

Portées et permissions

Les portées contrôlent les actions qu'une clé API est autorisée à effectuer. Appliquez le principe du moindre privilège — n'accordez que les portées nécessaires à votre intégration.

Portées disponibles

Portée	Description
`scans:create`	Soumettre de nouvelles analyses
`scans:read`	Voir les détails et le statut d'une analyse
`scans:list`	Lister toutes les analyses du tenant
`scans:cancel`	Annuler les analyses en cours
`results:read`	Récupérer les résultats et les découvertes
`templates:create`	Créer des modèles d'analyse
`templates:read`	Voir les modèles d'analyse
`templates:update`	Modifier les modèles d'analyse
`templates:delete`	Supprimer les modèles d'analyse
`webhooks:create`	Enregistrer et tester les webhooks
`webhooks:read`	Voir les configurations et journaux de livraison
`webhooks:update`	Modifier les paramètres des webhooks
`webhooks:delete`	Supprimer les webhooks
`usage:read`	Voir les analytiques d'utilisation et les quotas

Ensembles de portées recommandés

Pipeline CI/CD (lecture-écriture analyses) :

["scans:create", "scans:read", "scans:list", "results:read"]

Tableau de bord de surveillance (lecture seule) :

["scans:read", "scans:list", "results:read", "usage:read"]

Automatisation complète (analyses + webhooks + modèles) :

["scans:create", "scans:read", "scans:list", "scans:cancel", "results:read",
 "templates:create", "templates:read", "templates:update",
 "webhooks:create", "webhooks:read"]

Application des portées

Si une requête nécessite une portée que la clé API ne possède pas :

{
  "success": false,
  "error": "Portée insuffisante : nécessite scans:create",
  "code": "INSUFFICIENT_SCOPE"
}

Statut HTTP : 403 Forbidden

Types d'analyse autorisés

Restreignez les moteurs d'analyse qu'une clé API peut invoquer :

Isolez les clés CI/CD aux analyses de conteneurs uniquement (ex. : trivy)
Limitez les clés OSINT à la reconnaissance passive (ex. : harvester, sublist3r)
Restreignez les clés web aux scanners web (ex. : zap, nikto, wapiti)

Types d'analyse disponibles : nmap, zap, trivy, nuclei, nikto, sqlmap, wapiti, harvester, sublist3r, sentinel

Allowlisting IP

Verrouillez une clé API sur des adresses IP sources ou des plages CIDR spécifiques. Les requêtes provenant d'autres IP sont rejetées avec 403 IP_NOT_ALLOWED.

Formats pris en charge :

IP unique : "203.0.113.50"
Plage CIDR : "198.51.100.0/24"
IPv6 : "2001:db8::1"

IP dynamiques

Pour les runners CI/CD avec IP dynamiques (ex. : GitHub Actions), omettez allowedIpAddresses ou utilisez les plages CIDR publiées du runner.

Limites de débit

Les limites de débit protègent à la fois votre compte et la plateforme. Les limites sont appliquées sur trois fenêtres :

Fenêtre	Défaut	Plage configurable
Par minute	60	1 – 1 000
Par heure	1 000	1 – 50 000
Par jour	10 000	1 – 500 000

En-têtes de limite de débit

Chaque réponse inclut les informations de limite de débit :

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 42
X-RateLimit-Reset: 1709654460

Limite de débit dépassée

{
  "success": false,
  "error": "Limite de débit dépassée. Réessayez dans 23 secondes.",
  "code": "RATE_LIMIT_EXCEEDED"
}

Statut HTTP : 429 Too Many Requests

Implémentez un backoff exponentiel dans votre client :

import time

def appel_api_avec_retry(func, max_retries=3):
    for tentative in range(max_retries):
        response = func()
        if response.status_code != 429:
            return response
        attente = 2 ** tentative  # 1s, 2s, 4s
        time.sleep(attente)
    raise Exception("Limite de débit dépassée après les tentatives")

Rotation des clés

Effectuez la rotation des clés API avec zéro temps d'arrêt grâce au mécanisme de période de grâce. Pendant la période de grâce, l'ancienne et la nouvelle clé sont toutes deux valides.

Endpoint

POST /api/v1/api-keys/:keyId/rotate

Corps de la requête (optionnel)

{
  "gracePeriodHours": 24
}

Workflow de rotation

POST /api-keys/:ancienneCleId/rotate  → Nouvelle clé créée, ancienne en période de grâce
Mettez à jour votre magasin de secrets avec la nouvelle clé
Déployez la nouvelle clé dans vos services
L'ancienne clé expire automatiquement après la période de grâce

Bonne pratique

Effectuez la rotation des clés tous les 90 jours. Automatisez la rotation dans votre infrastructure ou définissez un rappel calendaire.

Révocation des clés

Désactivez immédiatement et définitivement une clé API. La révocation est instantanée — la clé cesse de fonctionner immédiatement sans période de grâce.

Endpoint

DELETE /api/v1/api-keys/:keyId

Corps de la requête

{
  "reason": "Clé compromise — rotation vers une nouvelle clé"
}

Après révocation, toute requête utilisant la clé révoquée retourne 401 KEY_REVOKED.

Statuts des clés

Statut	Description
`active`	La clé est pleinement opérationnelle
`revoked`	La clé a été définitivement désactivée
`expired`	La clé a dépassé sa date `expiresAt`
`suspended`	La clé a été temporairement suspendue par un administrateur

Seules les clés active peuvent authentifier les requêtes API.

Bonnes pratiques de sécurité

À faire

✅ Stockez les clés dans un gestionnaire de secrets (HashiCorp Vault, AWS Secrets Manager, Azure Key Vault)
✅ Utilisez des variables d'environnement — ne codez jamais les clés en dur
✅ Appliquez le moindre privilège — n'accordez que les portées nécessaires
✅ Définissez des dates d'expiration — rotation tous les 90 jours
✅ Utilisez l'allowlisting IP pour l'infrastructure statique
✅ Utilisez des limites par clé pour éviter l'automatisation incontrôlée
✅ Surveillez l'utilisation via les endpoints d'analytique d'utilisation
✅ Révoquez immédiatement si une clé est compromise

À ne pas faire

❌ Ne committez jamais les clés dans le contrôle de source (Git, SVN)
❌ Ne transmettez jamais les clés dans les paramètres d'URL
❌ Ne partagez jamais les clés entre équipes ou environnements
❌ Ne journalisez jamais les clés API dans les logs applicatifs
❌ N'utilisez jamais une seule clé pour tous les environnements — créez des clés séparées pour dev, staging, production

Exemple de variable d'environnement

# .env (jamais committé dans Git)
CERTIX_API_KEY=cix_sk_votre_cle_api_ici

import os
api_key = os.environ["CERTIX_API_KEY"]

apiKey := os.Getenv("CERTIX_API_KEY")

const apiKey = process.env.CERTIX_API_KEY;

Prochaines étapes :

Méthodes d'authentification​

Format des clés API​

Transmettre votre clé API​

Créer une clé API​

Endpoint​

Corps de la requête​

Paramètres de la requête​

Réponse (201 Created)​

Portées et permissions​

Portées disponibles​

Ensembles de portées recommandés​

Application des portées​

Types d'analyse autorisés​

Allowlisting IP​

Limites de débit​

En-têtes de limite de débit​

Limite de débit dépassée​

Rotation des clés​

Endpoint​

Corps de la requête (optionnel)​

Workflow de rotation​

Révocation des clés​

Endpoint​

Corps de la requête​

Statuts des clés​

Bonnes pratiques de sécurité​

À faire​

À ne pas faire​

Exemple de variable d'environnement​

Méthodes d'authentification

Format des clés API

Transmettre votre clé API

Créer une clé API

Endpoint

Corps de la requête

Paramètres de la requête

Réponse (201 Created)

Portées et permissions

Portées disponibles

Ensembles de portées recommandés

Application des portées

Types d'analyse autorisés

Allowlisting IP

Limites de débit

En-têtes de limite de débit

Limite de débit dépassée

Rotation des clés

Endpoint

Corps de la requête (optionnel)

Workflow de rotation

Révocation des clés

Endpoint

Corps de la requête

Statuts des clés

Bonnes pratiques de sécurité

À faire

À ne pas faire

Exemple de variable d'environnement