API-Zugang und API-Schlüssel

Über die Vizito-API lesen und schreiben Ihre eigenen Systeme Besucherdaten: Besucher an- und abmelden, registrierte Besucher mit einer anderen Datenbank abgleichen, Auswertungszahlen abrufen. Dieser Artikel behandelt, wie sich ein System dabei authentifiziert. Die Endpunkte selbst sind in der Vizito-API-Referenz dokumentiert.

Welche Authentifizierungsverfahren werden unterstützt?

Es gibt drei, und sie lassen sich nebeneinander verwenden:

Verfahren Was der Aufrufer sendet Wo das Geheimnis liegt
API-Schlüssel Authorization: Bearer vzk_... Vizito (gehasht)
Microsoft Entra ID Authorization: Bearer <Zugriffstoken> Ihr Entra-ID-Verzeichnis
Benutzername und Passwort HTTP Basic Vizito (das Backoffice-Passwort des Benutzers)

Die Basisauthentifizierung mit einem Backoffice-Login funktioniert weiterhin, und bestehende Integrationen laufen unverändert weiter. Empfohlen wird sie aber nicht mehr: Sie gibt Ihrer Integration dasselbe Geheimnis, das auch das Backoffice öffnet, sie lässt sich nicht wechseln, ohne die betreffende Person auszusperren, und es ist nicht nachvollziehbar, ob sie überhaupt noch genutzt wird. Bevorzugen Sie einen API-Schlüssel, oder Entra ID, wenn Ihre IT-Richtlinie verlangt, dass die Identität in Ihrem eigenen Verzeichnis liegt.

Was ist ein API-Schlüssel?

Ein API-Schlüssel ist ein eigenes Zugangsmittel für genau eine Integration. Er lässt sich widerrufen, mit einem Ablaufdatum versehen und auf feste IP-Adressen beschränken, ohne dass jemals ein Backoffice-Passwort geteilt wird. Nur globale Administratoren können API-Schlüssel verwalten.

Ein API-Schlüssel hat immer vollen Zugriff auf die Standorte, die er abdeckt, und überhaupt keinen Zugriff außerhalb davon. Er ist nicht an das Konto gebunden, das ihn erstellt hat, und funktioniert weiter, wenn sich dieses Konto ändert oder entfernt wird. Eine Integration bricht also nicht ab, weil eine Kollegin oder ein Kollege das Unternehmen verlässt.

Wie erstelle ich einen API-Schlüssel?

Schritt 1: Die Seite Integrationen öffnen

Melden Sie sich auf der Integrationsseite im Vizito-Backoffice an und scrollen Sie zu “API keys”. Sie müssen globaler Administrator sein, um diesen Abschnitt zu sehen.

Schritt 2: Den Schlüssel erstellen

Klicken Sie auf “Create API key” und füllen Sie aus:

  • Name: wofür der Schlüssel gedacht ist, zum Beispiel “Zutrittskontrollsystem”. Daran erkennen Sie ihn später in der Liste wieder.
  • Authentication: “Vizito API key”.
  • Locations: der Standort, auf dem Sie gerade sind, ist immer enthalten; markieren Sie jeden weiteren Standort, den der Schlüssel erreichen können soll. Aufgelistet sind nur Standorte, auf die Sie selbst Zugriff haben.
  • Expires: nie, oder nach 30 Tagen, 90 Tagen oder einem Jahr.
  • Allowed IP addresses: eine IP-Adresse oder ein CIDR-Bereich pro Zeile. Lassen Sie das Feld leer, damit der Schlüssel von überall verwendet werden darf.

Schritt 3: Den Schlüssel kopieren

Der Schlüssel wird nur einmal angezeigt, bei der Erstellung, und lässt sich danach nicht wieder abrufen. Kopieren Sie ihn direkt in das System, das ihn verwenden wird. Wenn Sie ihn verlieren, löschen Sie den Schlüssel und erstellen einen neuen.

Schritt 4: Ihn bei jeder Anfrage mitsenden

Setzen Sie den Schlüssel in einen Authorization-Header:

curl https://api.vizito.be/api/visitors/bycompany/<company id> \\
  -H "Authorization: Bearer vzk_1a2b3c4d5e6f7890_..."

X-API-Key: vzk_... funktioniert ebenfalls, für Clients, die keinen Authorization-Header setzen können.

Können wir uns stattdessen mit Microsoft Entra ID authentifizieren?

Ja. Vizito akzeptiert ein OAuth-2.0-Zugriffstoken, das Ihr eigener Entra-ID-Mandant ausstellt, sodass kein Vizito-Geheimnis irgendwo in Ihrer Infrastruktur gespeichert werden muss. Ihre Anwendung authentifiziert sich bei Entra ID über den Client-Credentials-Grant, entweder mit einem Client Secret oder mit einem Zertifikat, und sendet das erhaltene Token an Vizito. Was von beidem Sie verwenden, bleibt allein zwischen Ihrer Anwendung und Microsoft: Vizito sieht dieses Zugangsmittel nie.

Auf der Vizito-Seite muss in Entra ID nichts registriert werden, und es ist keine mandantenübergreifende Administratoreinwilligung nötig. Die Anwendungsregistrierung liegt in Ihrem Verzeichnis und bleibt unter Ihrer Kontrolle.

Schritt 1: Die App-Registrierung anlegen

Gehen Sie im Azure-Portal zu “Microsoft Entra ID” > “App registrations” > “New registration”. Geben Sie ihr einen Namen, wählen Sie “Accounts in this organizational directory only” und registrieren Sie sie. Sie brauchen weder eine Redirect-URI noch API-Berechtigungen.

Fügen Sie unter “Certificates & secrets” entweder ein Client Secret oder ein Zertifikat hinzu, je nachdem, was Ihre Richtlinie vorschreibt.

Notieren Sie sich auf der Seite “Overview”:

  • die Directory (tenant) ID
  • die Application (client) ID

Schritt 2: Die Anwendung in Vizito registrieren

Klicken Sie im Backoffice auf der Integrationsseite auf “Create API key” und setzen Sie “Authentication” auf “Microsoft Entra ID”. Fügen Sie die beiden IDs ein und wählen Sie dann Standorte, Ablauf und IP-Beschränkungen genau wie bei einem gewöhnlichen API-Schlüssel.

Lassen Sie “Audience” leer, sofern Sie keine Application ID URI veröffentlicht haben und Tokens daran binden möchten. Leer bedeutet, dass Vizito Tokens erwartet, die für die Anwendung selbst ausgestellt wurden, und genau das erzeugt die Anfrage im nächsten Schritt.

Schritt 3: Ein Token anfordern und die API aufrufen

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

Entra ID antwortet mit einem access_token, das etwa eine Stunde gültig ist. Senden Sie es als Bearer-Token:

curl https://api.vizito.be/api/visitors/bycompany/<company id> \\
  -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIs..."

Halten Sie das Token bis kurz vor Ablauf zwischengespeichert und fordern Sie danach ein neues an. Es ist nicht nötig, pro Aufruf ein frisches Token zu holen.

Was prüft Vizito am Token?

Bei jeder Anfrage:

  • die Signatur, gegen die von Ihrem Mandanten veröffentlichten öffentlichen Signaturschlüssel
  • dass das Token von dem Mandanten ausgestellt wurde, der am Zugangsmittel registriert ist
  • dass es für die Anwendung ausgestellt wurde, die am Zugangsmittel registriert ist
  • dass es ein Anwendungstoken aus dem Client-Credentials-Grant ist und kein Token, das im Namen eines angemeldeten Benutzers ausgestellt wurde
  • dass es nicht abgelaufen ist und dass die Audience passt

Schlägt eine dieser Prüfungen fehl, wird die Anfrage mit einem 401 abgelehnt. Dasselbe gilt, wenn das Zugangsmittel widerrufen wurde, abgelaufen ist oder von einer IP-Adresse außerhalb seiner Freigabeliste verwendet wird. Ein Entra-Zugangsmittel lässt sich also aus dem Backoffice genauso schnell abschalten wie ein API-Schlüssel.

Was darf ein Zugangsmittel?

Ein API-Schlüssel oder ein Entra-Zugangsmittel ist globaler Administrator auf den Standorten, die ihm zugewiesen wurden, und hat auf jeden anderen Standort überhaupt keinen Zugriff. Jede Anfrage, die einen Standort nennt, wird gegen diese Liste geprüft.

Benutzer oder API-Schlüssel kann es nicht verwalten. Ein abgeflossenes Zugangsmittel kann daher keine Backoffice-Logins anlegen, kein Passwort zurücksetzen und sich keine Ersatz-Zugangsmittel ausstellen. Genau das macht das Widerrufen wirksam.

Wie widerrufe oder lösche ich ein Zugangsmittel?

Verwenden Sie auf der Integrationsseite das Verbotssymbol, um ein Zugangsmittel zu widerrufen, und das Kreuz, um es zu löschen. Ein Widerruf behält die Zeile und ihre Historie, stoppt die Nutzung aber sofort: Die nächste Anfrage liest den Status neu, es gibt also keine Verzögerung und nichts abzuwarten. Löschen entfernt das Zugangsmittel vollständig.

Jede Integration, die dieses Zugangsmittel noch verwendet, hört sofort auf zu funktionieren, vergewissern Sie sich also, wofür es eingesetzt wird. Die Spalte “Last used” zeigt, wann das Zugangsmittel zuletzt eine Anfrage gestellt hat.

Fehlerbehebung

  • 401 bei jeder Anfrage: Prüfen Sie, ob der Header Authorization: Bearer <Schlüssel> lautet, mit einem Leerzeichen nach “Bearer”. Prüfen Sie bei Entra ID, ob Mandanten- und Anwendungs-ID im Backoffice exakt mit der App-Registrierung übereinstimmen.
  • “This Entra ID application is not registered as an API credential”: Das Token ist gültig, aber die Anwendung, für die es ausgestellt wurde, ist nicht im Backoffice registriert oder ist auf einem anderen Vizito-Konto registriert.
  • “Only application tokens are accepted”: Das Token wurde im Namen eines Benutzers ausgestellt statt über den Client-Credentials-Grant. Prüfen Sie, ob die Anfrage grant_type=client_credentials und scope=<client id>/.default verwendet.
  • 403 “not valid for that location”: Das Zugangsmittel deckt den Standort in der Anfrage nicht ab. Bearbeiten Sie es und markieren Sie diesen Standort.
  • 403 von einem neuen Server: Das Zugangsmittel hat eine IP-Freigabeliste, und der neue Server steht nicht darauf.
  • Der Schlüssel funktionierte nach einer Weile nicht mehr: Prüfen Sie die Spalte “Expires”. Ein abgelaufenes Zugangsmittel wird abgelehnt, bis ein neues erstellt wurde.