Authentification et portées

Chaque requête à l'API publique doit porter une clé API à longue durée de vie comme token bearer. Les portées contraignent ce que chaque clé est autorisée à faire — accordez uniquement ce dont votre intégration a réellement besoin.

Format du token bearer

Les clés API ressemblent à ceci :

scs_live_t9JQ10cDjddmslzv9mRKYqaDS5ZU1KuDH

Le préfixe scs_live_ identifie la clé comme un identifiant de production pour SecureCodingHub. Les tokens font 41 caractères au total (préfixe de 9 caractères + corps aléatoire de 32 caractères). Ils sont renvoyés exactement une fois lorsque la clé est créée.

Envoyez le token à chaque requête comme en-tête d'authentification Bearer standard :

Authorization: Bearer scs_live_t9JQ10cDjddmslzv9mRKYqaDS5ZU1KuDH

Création d'une clé API

Les clés API sont créées dans la console d'administration — non via l'API.

Connectez-vous à app.securecodinghub.com en tant qu'administrateur d'organisation.

Ouvrez Organisation → Clés API depuis la barre latérale.

Cliquez sur + Créer une nouvelle clé. Donnez à la clé un nom descriptif (par exemple GitHub Actions — CI ou Synchronisation BI Looker).

Cochez uniquement les portées dont l'intégration a besoin. Les portées en lecture seule sont surlignées en bleu, les portées en écriture en ambre.

(Facultatif) Définissez une date d'expiration. Les clés sans expiration restent valables jusqu'à ce que vous les révoquiez.

Cliquez sur Créer la clé. Le token complet est affiché dans une fenêtre modale. Copiez-la maintenant dans votre gestionnaire de secrets. Vous ne pourrez pas le récupérer à nouveau — seuls le préfixe et les quatre derniers caractères sont stockés.

Référence des portées

SecureCodingHub utilise 16 portées fines divisées en niveaux lecture et écriture. Une requête qui atteint un point de terminaison sans la portée correspondante renvoie 403 Forbidden avec le corps de réponse {"error":"insufficient_scope","required":"…","present":[…]}.

Portée	Ressource	Niveau	Accorde
`org:read`	Organisation	Lecture	Lire les métadonnées de l'organisation (nom, plan, sièges).
`users:read`	Utilisateurs	Lecture	Lister les utilisateurs ; récupérer le détail utilisateur.
`users:write`	Utilisateurs	Écriture	Créer, mettre à jour, désactiver les utilisateurs.
`teams:read`	Équipes	Lecture	Lister les équipes et les membres.
`teams:write`	Équipes	Écriture	Créer, mettre à jour, supprimer les équipes.
`assignments:read`	Affectations	Lecture	Lister les affectations ; récupérer le détail avec complétion.
`assignments:write`	Affectations	Écriture	Créer, mettre à jour, désactiver les affectations.
`custom-courses:read`	Cours personnalisés	Lecture	Lister les cours personnalisés avec leurs éléments.
`custom-courses:write`	Cours personnalisés	Écriture	Créer, mettre à jour, supprimer les cours personnalisés.
`progress:read`	Progression	Lecture	Progression de pratique et apprentissage par utilisateur.
`certificates:read`	Certificats	Lecture	Lister et télécharger les certificats.
`audit-log:read`	Journal d'audit	Lecture	Lister les entrées du journal d'audit.
`compliance:read`	Conformité	Lecture	Données du tableau de bord de conformité.
`content:read`	Contenu	Lecture	Sujets, scénarios, mappage CWE-vers-sujet.
`sarif:ingest`	SARIF	Écriture	Ingérer les exécutions SARIF et attribuer automatiquement la formation.
`webhook:manage`	Webhooks	Écriture	Gérer les points de terminaison webhook sortants.

Jeux de portées recommandés

Cas d'usage	Portées minimum
Ingestion SARIF CI/CD	`sarif:ingest`
Provisionnement utilisateur piloté par RH	`users:write`, `teams:write`
Export BI / rapport	`users:read`, `progress:read`, `assignments:read`, `audit-log:read`
Ticketing et SOAR (abonnés à événements)	`webhook:manage`, `assignments:read`
Export en lecture seule pour auditeur	`org:read`, `audit-log:read`, `compliance:read`, `certificates:read`

Rotation et révocation

Pour faire tourner une clé, créez d'abord un remplacement, déployez le nouveau token, puis révoquez l'ancien dans Organisation → Clés API. La révocation prend effet immédiatement — les requêtes en vol utilisant l'ancien token commenceront à renvoyer 401 Unauthorized en quelques secondes.

Si une clé est divulguée, révoquez-la. Il n'y a pas d'état « pause » ; la révocation est permanente. Le token ne peut pas être réactivé.

Bonne pratique de stockage

Traitez le token comme un mot de passe de base de données. Ne le commitez jamais dans le contrôle de source.
Préférez le magasin de secrets natif de votre plateforme (AWS Secrets Manager, GCP Secret Manager, GitHub Actions secrets, Vault, 1Password Connect).
En CI, injectez le token uniquement à l'étape qui en a besoin ; évitez de l'echoer.
Émettez une clé par intégration pour pouvoir révoquer indépendamment. Ne partagez pas une seule clé entre CI, BI et SOAR.
Définissez une expiration sur les tokens créés pour des intégrations à courte durée de vie (preuves de concept, évaluations de fournisseur).

Erreurs courantes

Statut	Réponse	Signification
`401`	`{"error":"unauthorized"}`	Token manquant, malformé, révoqué ou expiré.
`403`	`{"error":"insufficient_scope",…}`	Le token est valide mais manque de la portée requise pour ce point de terminaison.
`429`	`{"error":"rate_limited"}`	Plafond par minute ou par heure atteint. Voir Limites de débit.