Accès API et clés API

L’API Vizito permet à vos propres systèmes de lire et d’écrire des données visiteurs : enregistrer les arrivées et les départs, maintenir les visiteurs enregistrés synchronisés avec une autre base, extraire des chiffres de reporting. Cet article explique comment un système s’authentifie auprès d’elle. Les points de terminaison eux-mêmes sont documentés dans la référence de l’API Vizito.

Quelles méthodes d’authentification sont prises en charge ?

Il y en a trois, et elles peuvent coexister :

Méthode Ce que l’appelant envoie Où réside le secret
Clé API Authorization: Bearer vzk_... Vizito (haché)
Microsoft Entra ID Authorization: Bearer <jeton d'accès> Votre annuaire Entra ID
Nom d’utilisateur et mot de passe HTTP Basic Vizito (le mot de passe backoffice de l’utilisateur)

L’authentification basique avec un identifiant de backoffice fonctionne toujours et les intégrations existantes continuent de tourner, mais ce n’est plus la méthode recommandée : elle confie à votre intégration le secret même qui ouvre le backoffice, elle ne peut pas être renouvelée sans bloquer la personne concernée, et rien ne permet de savoir si elle est encore utilisée. Préférez une clé API, ou Entra ID si votre politique informatique impose que l’identité réside dans votre propre annuaire.

Qu’est-ce qu’une clé API ?

Une clé API est un identifiant distinct, destiné à une seule intégration. Elle peut être révoquée, dotée d’une date d’expiration et restreinte à des adresses IP fixes, sans jamais partager un mot de passe de backoffice. Seuls les administrateurs globaux peuvent gérer les clés API.

Une clé API dispose toujours d’un accès complet aux emplacements qu’elle couvre, et d’aucun accès en dehors de ceux-ci. Elle n’est pas liée au compte qui l’a créée et continue de fonctionner lorsque ce compte change ou est supprimé : une intégration ne casse donc pas parce qu’un collègue a quitté l’entreprise.

Comment créer une clé API ?

Étape 1 : ouvrir la page Intégrations

Connectez-vous à la page Intégrations du backoffice Vizito et faites défiler jusqu’à “Clés API”. Vous devez être administrateur global pour voir cette section.

Étape 2 : créer la clé

Cliquez sur “Créer une clé API” et renseignez :

  • Nom : à quoi sert la clé, par exemple “Système de contrôle d’accès”. C’est ce qui vous permettra de la reconnaître dans la liste par la suite.
  • Authentification : “Clé API Vizito”.
  • Emplacements : l’emplacement sur lequel vous vous trouvez est toujours inclus ; cochez tout autre emplacement que la clé doit pouvoir atteindre. Seuls les emplacements auxquels vous avez vous-même accès sont listés.
  • Expire : jamais, ou après 30 jours, 90 jours ou un an.
  • Adresses IP autorisées : une adresse IP ou une plage CIDR par ligne. Laissez ce champ vide pour autoriser l’utilisation de la clé depuis n’importe où.

Étape 3 : copier la clé

La clé n’est affichée qu’une fois, à sa création, et ne peut pas être récupérée ensuite. Copiez-la directement dans le système qui l’utilisera. Si vous la perdez, supprimez la clé et créez-en une nouvelle.

Étape 4 : l’envoyer à chaque requête

Placez la clé dans un en-tête Authorization :

curl https://api.vizito.be/api/visitors/bycompany/<id de la société> \
  -H "Authorization: Bearer vzk_1a2b3c4d5e6f7890_..."

X-API-Key: vzk_... fonctionne également, pour les clients qui ne peuvent pas définir d’en-tête Authorization.

Pouvons-nous nous authentifier avec Microsoft Entra ID à la place ?

Oui. Vizito accepte un jeton d’accès OAuth 2.0 émis par votre propre tenant Entra ID : aucun secret Vizito n’a donc à être stocké où que ce soit dans votre infrastructure. Votre application s’authentifie auprès d’Entra ID avec le flux client credentials, en utilisant soit un secret client, soit un certificat, et envoie le jeton obtenu à Vizito. Le choix entre les deux ne concerne que votre application et Microsoft : Vizito ne voit jamais cet identifiant.

Rien n’a à être enregistré côté Vizito dans Entra ID, et aucun consentement d’administrateur inter-tenant n’est nécessaire. L’enregistrement de l’application réside dans votre annuaire et reste sous votre contrôle.

Étape 1 : créer l’enregistrement d’application

Dans le portail Azure, allez dans “Microsoft Entra ID” > “App registrations” > “New registration”. Donnez-lui un nom, choisissez “Accounts in this organizational directory only” et enregistrez-la. Vous n’avez besoin ni d’URI de redirection ni d’autorisations d’API.

Sous “Certificates & secrets”, ajoutez soit un secret client, soit un certificat, selon ce que prescrit votre politique.

Depuis la page “Overview”, notez :

  • l’ID de l’annuaire (locataire)
  • l’ID d’application (client)

Étape 2 : enregistrer l’application dans Vizito

Dans le backoffice, sur la page Intégrations, cliquez sur “Créer une clé API” et réglez “Authentification” sur “Microsoft Entra ID”. Collez les deux identifiants, puis choisissez les emplacements, l’expiration et les restrictions d’IP exactement comme pour une clé API ordinaire.

Laissez “Audience” vide sauf si vous avez publié un URI d’ID d’application et souhaitez que les jetons y soient liés. Vide signifie que Vizito attend des jetons émis pour l’application elle-même, ce que produit la requête de l’étape suivante.

Étape 3 : demander un jeton et appeler l’API

curl -X POST https://login.microsoftonline.com/<id du tenant>/oauth2/v2.0/token \
  -d "grant_type=client_credentials" \
  -d "client_id=<id client>" \
  -d "client_secret=<secret client>" \
  -d "scope=<id client>/.default"

Entra ID répond avec un access_token valable environ une heure. Envoyez-le comme jeton bearer :

curl https://api.vizito.be/api/visitors/bycompany/<id de la société> \
  -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIs..."

Mettez le jeton en cache jusqu’à l’approche de son expiration et demandez-en un nouveau ensuite. Il est inutile d’obtenir un nouveau jeton à chaque appel.

Que vérifie Vizito à propos du jeton ?

À chaque requête :

  • la signature, au regard des clés de signature publiques publiées par votre tenant
  • que le jeton a bien été émis par le tenant enregistré sur l’identifiant
  • qu’il a bien été émis pour l’application enregistrée sur l’identifiant
  • qu’il s’agit d’un jeton d’application issu du flux client credentials, et non d’un jeton émis pour le compte d’un utilisateur connecté
  • qu’il n’a pas expiré, et que l’audience correspond

Si l’une de ces vérifications échoue, la requête est refusée avec un 401. Il en va de même lorsque l’identifiant a été révoqué, a expiré, ou est utilisé depuis une adresse IP hors de sa liste blanche : un identifiant Entra peut donc être désactivé depuis le backoffice aussi vite qu’une clé API.

Que peut faire un identifiant ?

Une clé API ou un identifiant Entra est administrateur global sur les emplacements qui lui ont été attribués, et n’a strictement aucun accès aux autres emplacements. Chaque requête nommant un emplacement est vérifiée par rapport à cette liste.

Il ne peut pas gérer les utilisateurs ni les clés API. Un identifiant divulgué ne peut donc pas créer d’accès au backoffice, réinitialiser le mot de passe de quiconque, ni émettre pour lui-même des identifiants de remplacement, et c’est ce qui rend sa révocation efficace.

Comment révoquer ou supprimer un identifiant ?

Sur la page Intégrations, utilisez l’icône d’interdiction pour révoquer un identifiant et la croix pour le supprimer. La révocation conserve la ligne et son historique mais interrompt immédiatement son fonctionnement : la requête suivante relit son statut, il n’y a donc aucun délai ni aucune attente. La suppression le retire entièrement.

Toute intégration utilisant encore cet identifiant cesse aussitôt de fonctionner : assurez-vous donc de savoir à quoi il sert. La colonne “Dernière utilisation” indique quand l’identifiant a effectué sa dernière requête.

Résolution des problèmes

  • 401 à chaque requête : vérifiez que l’en-tête est bien Authorization: Bearer <clé> avec une espace après “Bearer”. Pour Entra ID, vérifiez que les identifiants de tenant et d’application saisis dans le backoffice correspondent exactement à l’enregistrement d’application.
  • “This Entra ID application is not registered as an API credential” : le jeton est valide, mais l’application à laquelle il a été délivré n’est pas enregistrée dans le backoffice, ou est enregistrée sur un autre compte Vizito.
  • “Only application tokens are accepted” : le jeton a été émis pour le compte d’un utilisateur plutôt que par le flux client credentials. Vérifiez que la requête utilise grant_type=client_credentials et scope=<id client>/.default.
  • 403 “not valid for that location” : l’identifiant ne couvre pas l’emplacement indiqué dans la requête. Modifiez-le et cochez cet emplacement.
  • 403 depuis un nouveau serveur : l’identifiant dispose d’une liste blanche d’IP et le nouveau serveur n’y figure pas.
  • La clé a cessé de fonctionner au bout d’un moment : vérifiez la colonne “Expire”. Un identifiant expiré est refusé tant qu’un nouveau n’a pas été créé.