Authentification

Toutes les routes de l’API, sauf GET /v1/health et GET /v1/openapi.yaml, exigent une clé d’API envoyée dans l’en-tête Authorization :

Shell

curl https://aicscan.io/v1/workspace \
  -H "Authorization: Bearer aic_k3J9xQ2a_..."

Créer une clé#

Les clés se créent depuis l’espace client, page Clés d’API, par un propriétaire ou un administrateur de l’espace (un lecteur voit la liste, sans pouvoir créer ni révoquer) :

Donnez un nom à la clé (1 à 80 caractères), qui dit où elle sert : « ERP production », « Tableau de bord ».
Choisissez la portée : read (lecture seule) ou read + write (lecture et modification).
Choisissez, si vous le souhaitez, une expiration (30, 90, 180 ou 365 jours) ; sans expiration, la clé reste valable jusqu’à sa révocation.
Copiez la clé affichée : elle n’est montrée qu’une seule fois.

La création est refusée si l’offre de l’espace ne comprend pas l’API (plan_required, voir Offres et quotas), si le compte propriétaire est en cours de vérification (account_under_review), ou si l’espace a déjà 10 clés actives : révoquez d’abord une clé inutilisée. Chaque création et chaque révocation est inscrite au journal d’activité de l’espace, et les propriétaires en sont prévenus par email et sur les canaux de l’espace.

Format d’une clé#

Une clé a la forme aic_<préfixe>_<secret> :

aic_ permet aux outils de détection de secrets (dépôts Git, journaux) de la reconnaître ;
le préfixe de 8 caractères identifie la clé dans les listes et dans le journal d’activité de l’espace (par exemple aic_k3J9xQ2a) ;
le secret n’est connu que de vous : Aicscan ne conserve que l’empreinte SHA-256 de la clé complète.

La clé complète n’est montrée qu’une fois, à sa création. Une clé perdue ne se retrouve pas : créez-en une nouvelle et révoquez l’ancienne.

Un espace par clé#

Une clé appartient à un seul espace et ne voit que ses données. Une ressource d’un autre espace répond 404 not_found, exactement comme une ressource inexistante : son existence ne fuit pas.

Portées#

Portée	Méthodes autorisées
`read`	`GET` (et `HEAD`)
`write`	`POST`, `PATCH`, `DELETE`

write implique read : une clé émise avec write reçoit les deux portées. Une clé en lecture seule qui tente une écriture reçoit :

JSON

{
  "error": {
    "code": "insufficient_scope",
    "message": "This API key lacks the `write` scope.",
    "details": { "required_scope": "write", "key_scopes": ["read"] }
  }
}

La portée exigée par chaque point d’accès est indiquée dans la référence. Le flux temps réel demande la portée read.

Bonne pratique

Donnez à chaque intégration sa propre clé, avec la portée minimale : une clé read pour un tableau de bord ou un export, une clé read + write pour l’outil qui crée les règles. En cas de fuite, vous ne révoquez que celle-là.

Expiration, rotation et révocation#

Expiration : une clé peut être créée avec une durée de validité (30 à 365 jours depuis l’espace client, 1 à 3 650 jours pour une clé émise par l’équipe Aicscan). Passé ce délai, elle répond 401 api_key_expired.
Rotation : créez une nouvelle clé, déployez-la, vérifiez qu’elle est utilisée (GET /v1/workspace renvoie le préfixe de la clé appelante dans api_key.prefix ; la colonne « Dernière utilisation » de la page Clés d’API le montre aussi), puis révoquez l’ancienne. Les deux clés fonctionnent en même temps pendant la bascule.
Révocation : une clé révoquée cesse de fonctionner immédiatement (401 api_key_revoked). Les connexions temps réel ouvertes avec elle sont fermées au contrôle suivant (au plus 60 secondes, code 4401).

La révocation se fait depuis la page Clés d’API, avec confirmation ; elle s’applique aussi aux clés émises pour vous par l’équipe Aicscan, qui y apparaissent avec l’auteur « Équipe Aicscan ». Une clé compromise doit être révoquée sans attendre. Besoin d’aide (clé avec une limite de débit propre, doute sur une utilisation) : support@aicscan.io.

Erreurs d’authentification#

HTTP	Code	Cause
401	`missing_api_key`	En-tête `Authorization` absent, ou schéma autre que `Bearer`.
401	`invalid_api_key`	Clé inconnue ou mal formée.
401	`api_key_revoked`	Clé révoquée.
401	`api_key_expired`	Clé expirée.
403	`workspace_suspended`	Espace suspendu : contactez support@aicscan.io.
403	`account_under_review`	Le compte propriétaire de l’espace est en cours de vérification.
403	`plan_required`	L’offre de l’espace ne comprend pas l’API.
403	`insufficient_scope`	La clé n’a pas la portée exigée.

Les réponses 401 portent un en-tête WWW-Authenticate: Bearer realm="aicscan" (avec error="invalid_token" pour une clé refusée).

Les contrôles sont faits dans cet ordre : clé, espace suspendu, compte à vérifier, offre, débit, portée, quota quotidien. La liste complète des codes est dans Erreurs.

Compte en cours de vérification#

Pour prévenir les comptes multiples, un espace dont le propriétaire est en cours de vérification, et qui n’a pas d’abonnement payant en cours (un essai ne compte pas), reçoit 403 account_under_review avec details.reason = "multi_account_review" sur toutes les routes authentifiées. L’accès revient dès la validation du compte par l’équipe Aicscan ou la souscription d’une offre payante.

Sécurité des clés#

Ne placez jamais une clé dans du code exécuté par un navigateur ou une application mobile : elle donnerait accès à tout l’espace. Appelez l’API depuis votre serveur.
Les requêtes sont servies en HTTPS uniquement.
La dernière utilisation (date et adresse IP) de chaque clé est enregistrée et visible dans la page Clés d’API : révoquez la clé et écrivez à support@aicscan.io pour toute utilisation que vous ne reconnaissez pas.