Zum Hauptinhalt springen

API-Benutzer

Ein API-Benutzer ist ein eigener Benutzertyp für den programmatischen Zugriff auf die Netxp-Verein-API. Er wird nicht von einem Menschen zum Arbeiten in der Software verwendet, sondern von einer Anwendung — etwa einem Webformular für Eintritte, einem Datenabgleich oder einer selbst erstellten Auswertung.

Kein Benutzer hat automatisch API-Zugriff

Auch der Admin hat nicht von sich aus Zugriff auf einen API-Schlüssel. Wer die API nutzen möchte, muss dafür ausdrücklich über diesen Weg freigeschaltet werden.

Zweck​

  • Zugriff auf die Netxp-Verein-API einrichten
  • Eigene Funktionen umsetzen: Webformulare für Eintritt oder Datenänderung, eigene Geburtstags- und Jubiläumslisten, Datenabgleiche mit Fremdsystemen
  • Den Umfang des Zugriffs über Benutzerrollen begrenzen
  • Einstieg in die Verwaltung der API-Clients

Voraussetzungen​

  • Sie sind als Admin angemeldet.
  • Netxp-Verein Pro ist gebucht — sonst ist der Benutzertyp API-Benutzer im Auswahldialog ausgegraut.

So gehen Sie vor​

API-Benutzer anlegen​

  1. Benutzer → Benutzerliste öffnen.
  2. Links unten einen neuen Benutzer anlegen.
  3. Im Dialog „Benutzererstellung wählen" die Art „API-Benutzer" auswählen und bestätigen.
  4. Die Oberfläche Benutzerdetails – API-Benutzer öffnet sich.
„API-Benutzer" ist ausgegraut

Dann ist Netxp-Verein Pro für Ihren Verein nicht gebucht. Über den Link „hier bestellen" im Dialog gelangen Sie direkt zur Buchung der Zusatzleistung.

Pflichtangaben erfassen​

Im Bereich Personeninformation und Zugangsdaten sind folgende Angaben erforderlich:

FeldHinweis
BenutzernameMuss im Verein eindeutig sein.
Passwort + BestätigungMindestens 8 Zeichen (je nach Einstellung 10) sowie mindestens eine Zahl oder ein Sonderzeichen. Über „Passwort erstellen" erzeugt Netxp-Verein ein zufälliges, regelkonformes Passwort.
VornamePflicht.
NachnamePflicht.
E-Mail-AdressePflicht, wird auf Gültigkeit geprüft.

Anschließend speichern.

Passwort sofort notieren

Das Passwort wird nach dem Speichern nicht mehr angezeigt. Notieren Sie es sofort und legen Sie es sicher ab (Passwort-Manager). Wird es vergessen, muss es ein Neues gesetzt werden. Dabei ändert sich auch der API-Schlüssel.

Benutzerrollen zuweisen​

Im Bereich Benutzerrollen legen Sie fest, worauf der API-Zugriff inhaltlich zugreifen darf.

  1. Über „Hinzufügen" eine oder mehrere Benutzerrollen auswählen.
  2. Zum Entziehen die Rolle markieren und „Entfernen" klicken.
  3. Speichern.
Rollen so gering wie möglich halten

Legen Sie für den API-Zugriff eine eigene Rolle an, statt eine Verwaltungsrolle wiederzuverwenden. So bleibt der Umfang nachvollziehbar und lässt sich später gefahrlos ändern.

Der API-Schlüssel​

Der API-Schlüssel ist der Zugangs-Schlüssel des API-Benutzers. Er wird automatisch aus dem Passwort gebildet, sobald der Benutzer angelegt wird — Sie müssen ihn nicht selbst erzeugen oder erstellen.

VorgangWirkung auf den Schlüssel
Benutzer wird angelegtSchlüssel wird erzeugt und einmalig angezeigt
Passwort wird geändertBisheriger Schlüssel verfällt, ein neuer wird erzeugt
Benutzer wird gesperrt oder gelöschtSchlüssel verliert seine Gültigkeit
Der aktive Schlüssel wird beim Öffnen nicht angezeigt

Aus Sicherheitsgründen zeigt die Oberfläche den derzeit gültigen Schlüssel beim erneuten Öffnen des Benutzers nicht an. Ist er nicht mehr bekannt, erzeugen Sie über die Schaltfläche neben dem Feld API-Schlüssel einfach einen neuen — der bisherige verfällt dabei sofort, und alle Anwendungen, die ihn verwenden, müssen nachgezogen werden.

Der API-Schlüssel gewährt vollständigen Zugriff

Der Schlüssel ermöglicht vollen Zugriff auf Ihre Daten in Netxp-Verein. Geben Sie ihn ausschließlich auf gesichertem Weg an den vorgesehenen Empfänger weiter — nicht per unverschlüsselter E-Mail oder Chat. Besteht der Verdacht eines Vorfalls, sperren Sie den Benutzer umgehend; der Schlüssel ist damit sofort wertlos.

Zugang zu den API-Clients​

Am unteren Rand der Benutzerdetails führt die Schaltfläche „API-Clients" in die Verwaltung der OAuth-/OpenID-Connect-Clients.

API-Clients gehören nicht zu diesem Benutzer

Die Client-Liste ist vereinsweit und vom API-Benutzer unabhängig: Bei jedem Ihrer API-Benutzer sehen Sie dieselben API-Clients aufgelistet. Einzelheiten siehe API-Clients.

Die Schaltfläche erscheint nur, wenn Sie mindestens Leserecht auf API-Clients besitzen.

Tipps & Hinweise​

Ein API-Benutzer pro Zweck

Legen Sie je Anwendung einen eigenen API-Benutzer mit eigener Rolle an. Muss ein Zugriff beendet werden, sperren Sie genau diesen Benutzer — die übrigen Anbindungen laufen weiter.

Sprechende Namen verwenden

Ein Benutzername wie api_webformular oder api_abgleich_kasse macht auch nach Jahren noch nachvollziehbar, wozu der Zugang gehört.

Zugänge regelmäßig prüfen

Gehen Sie die API-Benutzer einmal jährlich durch und sperren Sie Zugänge, deren Anwendung nicht mehr betrieben wird.

Häufige Fehler​

„Dieser Benutzername ist bereits vergeben."

Der Benutzername muss im Verein eindeutig sein — auch gegenüber regulären Benutzern. Wählen Sie einen anderen.

Passwort wird nicht angenommen

Es muss mindestens 8 Zeichen lang sein (je nach Einstellung Ihres Vereins 10) und mindestens eine Zahl oder ein Sonderzeichen enthalten. Passwort und Bestätigung müssen übereinstimmen. Über „Passwort erstellen" erzeugt Netxp-Verein ein passendes Passwort.

API-Zugriff funktioniert plötzlich nicht mehr

Häufigste Ursache: Beim Benutzer wurde das Passwort geändert — damit verfällt der bisherige API-Schlüssel. Neuen Schlüssel erzeugen und in der Anwendung nachtragen. Weitere Ursachen: Der Benutzer wurde gesperrt oder gelöscht, oder ihm fehlt eine Benutzerrolle mit den benötigten Rechten.

Zugriff wird trotz gültigem Schlüssel verweigert

Prüfen Sie die zugewiesenen Benutzerrollen. Der API-Benutzer kann nur, was seine Rollen erlauben — die Rechtematrix in der Oberfläche zeigt den tatsächlichen Umfang.

Verwandte Themen​