Créer un compte dédié à l'usage de l'API

Toute intégration de l'API Certificall (création de dossiers depuis votre logiciel, dépôt de documents, suivi de consommation, boutons Certilink…) s'authentifie avec un nom d'utilisateur et un mot de passe, exactement comme une personne. Plutôt que de réutiliser les identifiants d'un collaborateur, créez un compte dédié à l'API : un utilisateur technique, sans autre usage, avec uniquement les droits dont votre intégration a besoin.

Ce guide vous explique comment créer ce compte depuis l'interface d'administration, définir son mot de passe, choisir ses droits et transmettre les identifiants à votre équipe technique sans les exposer.

Pourquoi un compte séparé ?

• Continuité : si le collaborateur quitte l'entreprise ou change de mot de passe, votre intégration continue de fonctionner.
• Moindre privilège : le compte ne porte que les droits API nécessaires, rien de plus.
• Traçabilité : les dossiers créés par l'intégration sont rattachés à ce compte, et non à une personne.
• Révocation simple : en cas de doute, vous changez son mot de passe ou supprimez le compte sans impacter personne.

Pré-requis

Pré-requis	Détail
Un accès à l'interface admin	admin.certificall.app, avec un rôle Gestionnaire ou Revendeur disposant du droit de créer des utilisateurs. Voir Les rôles sur l'interface admin.
Des droits API sur votre propre compte	Vous ne pouvez déléguer que les droits que vous possédez. Si la rubrique API n'apparaît pas dans les permissions à l'étape 4, demandez à votre contact Certificall d'activer les droits API sur votre entreprise.
Une adresse e-mail dédiée	L'adresse e-mail sert de nom d'utilisateur et doit être unique dans Certificall. Prévoyez une adresse technique (par exemple api@votre-entreprise.fr) ou un alias (prenom.nom+api@votre-entreprise.fr).

Étape 1 — Ouvrir la liste des utilisateurs de votre entreprise

1. Connectez-vous sur admin.certificall.app.
2. Ouvrez la fiche de votre entreprise, puis l'onglet Utilisateurs.
3. Cliquez sur Ajouter un utilisateur. Le panneau Créer un utilisateur s'ouvre sur la droite.

Revendeurs

Si vous gérez des entreprises enfants, ouvrez d'abord la fiche de l'entreprise concernée : le compte API est créé dans l'entreprise à laquelle les dossiers doivent être rattachés.

Étape 2 — Renseigner les informations du compte

Dans la section Informations :

• Prénom / Nom : choisissez des valeurs qui identifient clairement l'usage, par exemple API / Intégration ERP ou API / Site web. C'est ce libellé qui apparaîtra dans la liste des utilisateurs et sur les dossiers créés par l'intégration.
• Email : l'adresse technique choisie ci-dessus. Elle devient le nom d'utilisateur (username) que votre intégration enverra à l'API pour s'authentifier.

Une adresse, un compte

Une adresse e-mail ne peut être associée qu'à un seul compte. Si vous créez plusieurs comptes API (un par environnement, un par logiciel…), utilisez une adresse ou un alias différent pour chacun.

Étape 3 — Définir le mot de passe

Dans la section Mot de passe :

1. Cliquez sur Générer un mot de passe : Certificall remplit le champ Mot de passe et le champ Confirmation du mot de passe avec une valeur aléatoire robuste. C'est la méthode recommandée pour un compte technique : personne n'a à le mémoriser.
2. Cliquez sur Copier le mot de passe généré et collez-le immédiatement dans votre gestionnaire de mots de passe (voir l'étape 5). Le mot de passe n'est plus consultable une fois le compte enregistré.

Si vous préférez saisir votre propre mot de passe, il doit respecter les règles suivantes :

• au moins 6 caractères (visez beaucoup plus pour un compte technique : 20 caractères ou plus) ;
• au moins une majuscule, une minuscule et un chiffre ;
• aucun espace.

Ne réutilisez jamais un mot de passe existant

Le mot de passe d'un compte API est stocké dans la configuration de votre logiciel. Il doit être unique, généré aléatoirement, et n'être utilisé nulle part ailleurs.

Étape 4 — Choisir le rôle et les droits

Dans la section Rôle :

1. Sélectionnez le rôle Gestionnaire. C'est ce rôle qui fait apparaître le bloc Permissions ; le rôle Utilisateur de l'application ne donne accès qu'à l'application mobile et ne convient pas à un usage API.
2. Dans le bloc Permissions, dépliez la rubrique API et cochez uniquement les droits nécessaires à votre intégration.
3. Laissez décochés tous les droits de la rubrique Interface administration : un compte API n'a aucune raison de se connecter à l'interface admin.

Quels droits API cocher ?

Rubrique	Droit	À cocher si votre intégration…
Dossier	Créer	crée des dossiers, dépose des documents sur une étape Upload document, ferme des dossiers. C'est le droit minimal de la quasi-totalité des parcours.
Dossier	Consulter	lit le contenu ou le statut des dossiers, télécharge les PDF.
Dossier	Mettre à jour	modifie un dossier existant (métadonnées, référence de rapport…).
Dossier	Supprimer	supprime des dossiers. À n'accorder qu'en cas de besoin avéré.
Item	Créer	envoie elle-même des photos, vidéos ou signatures dans un dossier. Inutile pour un simple dépôt de document.
Certilink	Créer / Consulter / Mettre à jour / Supprimer	génère ou gère des Certilinks (liens de capture envoyés à vos clients ou intégrés à vos écrans).
Trame	Consulter	liste les trames disponibles pour retrouver un frameId.
Trame	Créer / Mettre à jour / Supprimer	administre les trames par API. Réservé aux intégrations avancées.

Pour savoir précisément quel droit chaque endpoint exige, reportez-vous à la documentation développeur : Gestion des dossiers, Gestion des items, Certilink.

Droits attribués uniquement par Certificall

Certains droits ne se cochent pas dans ce formulaire et sont attribués par votre contact Certificall, par exemple le droit de suivi de consommation décrit dans Suivre sa consommation. Si un endpoint vous répond 403 alors que le compte est correctement configuré, c'est probablement l'un de ces droits qui manque.

Cliquez enfin sur Enregistrer. Le compte apparaît dans la liste des utilisateurs avec le statut Activé.

Étape 5 — Partager les identifiants de manière sécurisée

Le compte vient d'être créé et vous êtes la seule personne à connaître son mot de passe. Il faut maintenant le transmettre à l'équipe qui développe ou exploite l'intégration, sans qu'il traîne ensuite dans une boîte mail ou une messagerie.

À faire

• Passer par un gestionnaire de mots de passe d'entreprise (Bitwarden, 1Password, KeePass, Vaultwarden, Dashlane…) : créez l'entrée dans un coffre partagé avec les seules personnes concernées. C'est la méthode à privilégier : le secret reste chiffré, l'accès est révocable et l'historique est tracé.
• À défaut, utiliser un lien à usage unique qui s'autodétruit après lecture ou après un délai court (fonction « Send » de Bitwarden, Password Pusher, One-Time Secret ou l'outil équivalent validé par votre service informatique).
• Séparer les canaux : si vous devez tout de même communiquer le secret en direct, envoyez le nom d'utilisateur par un canal et le mot de passe par un autre (e-mail puis appel téléphonique, par exemple), et jamais dans le même message.
• Côté intégration, demandez que les identifiants soient stockés dans un gestionnaire de secrets ou des variables d'environnement de la plateforme d'hébergement, et non dans le code source ou un fichier versionné.

À ne pas faire

• Envoyer le mot de passe en clair par e-mail, SMS ou messagerie instantanée (Teams, Slack, WhatsApp…), même à une seule personne, même « pour cette fois ».
• Le coller dans un ticket, un document partagé, un wiki, un commentaire de code ou un dépôt Git.
• Réutiliser le compte API pour se connecter à l'interface admin ou à l'application mobile.
• Partager un même compte API entre plusieurs logiciels ou plusieurs prestataires : créez un compte par intégration, vous pourrez ainsi en révoquer un sans arrêter les autres.

Vérifier que le compte fonctionne

Une fois les identifiants transmis, l'équipe technique peut vérifier immédiatement le compte en demandant un token :

curl -X POST https://admin.certificall.app/certificall/api/auth/token \
  -H "Content-Type: application/json" \
  -d '{ "username": "api@votre-entreprise.fr", "password": "le_mot_de_passe_genere" }'

Une réponse 200 contenant un token confirme que le compte est actif. Le détail de l'authentification est décrit dans Authentification publique.

Au quotidien : entretenir le compte

• Changer le mot de passe : ouvrez l'onglet Utilisateurs, cliquez sur Modifier l'utilisateur, puis saisissez un nouveau mot de passe (et sa confirmation) dans la section Mot de passe. Utilisez votre gestionnaire de mots de passe pour en générer un. Pensez à mettre à jour la configuration de l'intégration en parallèle, puis à remplacer l'entrée dans votre gestionnaire de mots de passe.
• Quand renouveler : au départ d'une personne qui connaissait le secret, au changement de prestataire, au moindre soupçon de fuite, et de façon planifiée (par exemple une fois par an).
• Ajuster les droits : depuis Modifier l'utilisateur, section Rôle, cochez ou décochez les permissions API au fil de l'évolution de votre intégration. Le changement est immédiat pour les nouveaux tokens.
• Décommissionner : lorsqu'une intégration est arrêtée, supprimez le compte via Supprimer l'utilisateur, ou à défaut changez son mot de passe sans le communiquer.

Récapitulatif

1. Utilisateurs → Ajouter un utilisateur dans la fiche de votre entreprise.
2. Prénom / Nom explicites, e-mail technique dédié (ce sera le username).
3. Générer un mot de passe, le copier et le mettre tout de suite à l'abri.
4. Rôle Gestionnaire, rubrique API uniquement, droits au strict nécessaire.
5. Transmettre les identifiants via un coffre partagé ou un lien à usage unique, jamais en clair.