Administrateurs

Clés API

Émettre, modifier et révoquer les clés des systèmes sectoriels qui transmettent des valeurs par l'interface applicative, et expliquer au système appelant comment signer ses requêtes.

Pour qui : Administrateurs nationaux, super-administrateurs, équipes techniques des systèmes sectoriels Dernière mise à jour : 29 septembre 2026

L'écran Clés d'accès applicatif (/administration/cles-api) gère l'accès des systèmes sectoriels (santé, agriculture, hydraulique, éducation, protection sociale) qui transmettent des valeurs d'indicateurs par l'interface applicative, sans passer par un fichier. « Chaque envoi est signé, passe par le staging et suit le circuit de validation. » L'écran se trouve dans l'onglet Données de la console et s'ouvre avec la permission Administrer le connecteur DHIS2, commune aux passerelles entrantes (super-administrateur et administrateur national par défaut).

Les valeurs reçues entrent au statut soumis : aucune n'est publiée sans validation humaine, et une valeur déjà validée n'est jamais remplacée par cette voie (l'écriture devient un conflit).

La liste des clés #

Colonne	Contenu
Organisation	Système ou institution émettrice, avec la note interne abrégée
Identifiant	Identifiant public, de la forme `pnin_` suivi de 24 caractères
Périmètre	Indicateurs autorisés (ou Tout le référentiel) et territoires autorisés (ou Tout le territoire)
État	Active, Révoquée ou Expirée, avec la date d'expiration ou Sans expiration
Dernière utilisation	Date, heure et adresse IP du dernier appel accepté, ou Jamais utilisée
Envois reçus	Nombre d'ingestions produites par la clé
Actions	Modifier et Révoquer, absents pour une clé révoquée

Le bouton Voir les envois ouvre le journal des ingestions filtré sur le canal API entrante.

Clés d'accès applicatif : colonnes Organisation, Identifiant, Périmètre et État

Émettre une clé #

Dans l'onglet Données, cliquez sur l'entrée Clés d'accès applicatif, puis sur Nouvelle clé (/administration/cles-api/nouvelle).
Remplissez le formulaire.
Cliquez sur Enregistrer.

Champ	Contenu
Organisation	Obligatoire, 255 caractères au plus. Par exemple la direction des statistiques agricoles.
Requêtes par minute	De 1 à 1000, 60 par défaut. Toutes les tentatives comptent, y compris celles dont la signature est fausse.
Indicateurs autorisés	Codes d'indicateurs séparés par des virgules ou des retours à la ligne. Vide : tout le référentiel.
Territoires autorisés	Codes de provinces ou de communes (une province couvre ses communes), ou « national ». Vide : tout le territoire.
Expire le	Facultatif, date postérieure à aujourd'hui
Note interne	Facultative

Un code inconnu est refusé avec le message « Codes inconnus : ... ».

L'écran Secret de la clé s'affiche alors avec l'organisation, l'Identifiant et le Secret (48 caractères). « Copiez ce secret maintenant et transmettez-le au système émetteur par un canal sûr. Il ne sera plus jamais affiché. » Cliquez ensuite sur Retour à la liste des clés.

Secret de la clé affiché une seule fois après émission (masqué sur la capture)

Modifier une clé #

Cliquez sur Modifier sur la ligne de la clé. L'écran Modifier la clé reprend les mêmes champs ; l'identifiant est affiché sans pouvoir être changé, et le secret reste le même. Après Enregistrer, le message « Clé mise à jour. » s'affiche.

Révoquer une clé #

Cliquez sur Révoquer sur la ligne de la clé.
Confirmez : « Révoquer cette clé ? Le système émetteur ne pourra plus rien transmettre avec elle. Cette action est définitive. »
Le message « Clé révoquée. » s'affiche.

L'émission et la révocation sont consignées au journal d'audit, avec l'identifiant et l'organisation ; chaque envoi reçu y est aussi tracé.

Ce que le système appelant doit faire #

Transmettez ces informations à l'équipe technique du système émetteur, avec l'identifiant et le secret.

Adresses disponibles #

L'adresse de base est https://pnisan.bi/api/v1. Tout échange est en JSON, en UTF-8, et les messages d'erreur sont en français.

Méthode et adresse	Rôle
`POST /api/v1/valeurs`	Dépose un lot de 500 valeurs au plus
`GET /api/v1/ingestions/{id}`	Suit un envoi de la même clé
`GET /api/v1/referentiel`	Indicateurs du périmètre de la clé
`GET /api/v1/territoires`	Provinces et communes du périmètre de la clé

Les trois en-têtes #

En-tête	Contenu
`X-Cle`	Identifiant de la clé
`X-Horodatage`	Instant de la requête, en secondes depuis le 1er janvier 1970 (UTC)
`X-Signature`	Signature HMAC-SHA256 en hexadécimal minuscule

Construire la signature #

La chaîne à signer compte quatre lignes séparées par un saut de ligne (\n), sans saut de ligne final :

METHODE
CHEMIN
HORODATAGE
EMPREINTE_DU_CORPS

METHODE : GET ou POST, en majuscules.
CHEMIN : chemin tel qu'il est envoyé, paramètres de requête compris, par exemple /api/v1/valeurs.
HORODATAGE : la valeur exacte de l'en-tête X-Horodatage.
EMPREINTE_DU_CORPS : empreinte SHA-256 hexadécimale du corps brut. Pour un GET sans corps, c'est l'empreinte de la chaîne vide.

La signature est le HMAC-SHA256 de cette chaîne, avec le secret pour clé. Exemple en ligne de commande :

HORO=$(date +%s)
CORPS='{"valeurs":[{"indicateur":"NUT-01","code_territoire":"BI-GI","periode_debut":"2026-01-01","valeur":42.5,"effectif":1200}]}'
EMPREINTE=$(printf '%s' "$CORPS" | sha256sum | cut -d' ' -f1)
SIGNATURE=$(printf 'POST\n/api/v1/valeurs\n%s\n%s' "$HORO" "$EMPREINTE" | openssl dgst -sha256 -hmac "$SECRET" | cut -d' ' -f2)
curl -X POST https://pnisan.bi/api/v1/valeurs -H "Content-Type: application/json" -H "X-Cle: $IDENTIFIANT" -H "X-Horodatage: $HORO" -H "X-Signature: $SIGNATURE" --data "$CORPS"

Contrôles appliqués, dans l'ordre #

Contrôle	Réponse en cas d'échec
Les trois en-têtes sont présents	401, « Authentification requise : les en-têtes X-Cle, X-Horodatage et X-Signature sont obligatoires. »
La clé existe	401, « Clé inconnue. »
Le plafond par minute n'est pas atteint	429, « Trop de requêtes pour cette clé. Réessayez dans ... secondes. » avec l'en-tête `Retry-After`
La clé n'est ni révoquée ni expirée	401, « Cette clé a été révoquée. » ou « Cette clé a expiré le ... »
L'horodatage est un nombre de secondes, à moins de cinq minutes de l'horloge du serveur	401, « Horodatage invalide ... » ou « Horodatage hors de la fenêtre admise de 5 minutes. Vérifiez l'horloge du système émetteur. »
La signature est exacte	401, « Signature invalide. Vérifiez la chaîne signée (méthode, chemin, horodatage, empreinte du corps) et le secret. »
La signature n'a jamais servi	409, « Requête déjà reçue : une signature ne peut servir qu'une fois. »

Une valeur hors du périmètre de la clé est écartée ligne par ligne (« Indicateur hors du périmètre de la clé », « Territoire hors du périmètre de la clé »), sans bloquer les autres lignes du lot. Le suivi des envois se fait dans le journal des ingestions, canal API entrante.