Authentification
Chaque requête à l'API publique porte une paire d'identifiants — nb_pub_* (clé publique) + nb_sec_* (secret). Le secret est envoyé en tant que Bearer token. L'identifiant est restreint à une seule organisation + un catalogue de scopes fixe.
Émettre des identifiants
- Connectez-vous à votre organisation sur app.nexbasira.com.
- Allez dans Admin → Identifiants API.
- Cliquez sur Émettre un identifiant, choisissez un nom + des scopes, confirmez.
- Copiez la paire
nb_pub_*+nb_sec_*. Le secret n'est affiché qu'une seule fois. Stockez-le immédiatement dans votre gestionnaire de secrets — nous n'en conservons qu'un hachage SHA-256 de notre côté.
Utiliser l'identifiant
Authorization: Bearer nb_sec_AbCdEf... La clé publique (nb_pub_*) identifie l'identifiant dans nos logs + apparaît dans l'en-tête NB-Credential-Id des livraisons de webhook. Le secret authentifie.
curl https://app.nexbasira.com/api/v1/public/sessions \
-H "Authorization: Bearer nb_sec_..."Catalogue de scopes
Chaque identifiant est créé avec un ensemble de scopes explicite. Les requêtes hors de ces scopes renvoient 403. Le catalogue de scopes est fixe (pas de scopes personnalisés en v1) :
| Portée | Accorde |
|---|---|
sessions:read | Lister + récupérer les sessions |
sessions:write | Créer des sessions + les terminer |
participants:read | Lister les participants d'une session |
participants:write | Émettre des invitations d'utilisateur terrain |
evidence:read | Lister + récupérer les lignes de preuve + les URL de téléchargement signées |
recordings:read | Lire les métadonnées des artefacts d'enregistrement + les URL de téléchargement |
audit:read | Lire la chaîne d'audit par session + les coordonnées d'ancrage TSA |
webhooks:read | Lister les endpoints de webhook enregistrés + le journal des livraisons |
webhooks:write | Enregistrer / faire tourner le secret / supprimer des endpoints de webhook |
branding:read | Lire le branding de l'organisation (logo / couleurs / pied de page PDF) |
branding:write | Modifier le branding de l'organisation |
org:read | Lire les métadonnées de l'organisation |
whiteboards:read | Lister les tableaux blancs par session |
Rotation
Pour effectuer la rotation sans interruption :
- Émettez un nouvel identifiant avec le même ensemble de scopes.
- Déployez le nouveau secret dans votre application.
- Vérifiez que le nouvel identifiant reçoit du trafic (Admin → Identifiants API affiche l'horodatage de dernière utilisation).
- Révoquez en douceur l'ancien identifiant. Les requêtes existantes qui l'utilisent renvoient 401 ; la piste d'audit des appels passés reste intacte.
Vérification en temps constant
Côté backend, les secrets sont stockés sous la forme SHA-256(secret + SECRET_KEY_pepper) et comparés en temps constant (hmac.compare_digest). Un dump de hachages divulgué ne peut pas être forcé par force brute jusqu'au texte en clair sans casser aussi le pepper.
Ce que cet identifiant n'accorde PAS
- L'accès admin à la SPA — c'est distinct (connexion opérateur + RBAC).
- La connexion côté terrain — elle utilise des URL signées à usage unique émises via
sessions.invite(). - Le provisionnement SCIM — utilise un bearer token distinct propre à chaque organisation, voir Provisionnement SCIM.
- La signature des webhooks — elle se fait avec le secret
whsec_*propre à chaque endpoint, voir Webhooks.
Piste d'audit
Chaque appel à l'API est journalisé avec la clé publique de l'identifiant + l'endpoint + le statut. Les opérations qui modifient l'état écrivent en plus des lignes d'audit dans l'organisation concernée. L'administrateur peut consulter l'activité de l'identifiant dans Admin → Identifiants API → [identifiant] → Activité.