API-Clients (OAuth / OpenID Connect)

Über API-Clients binden Sie eigene oder fremde Anwendungen an Netxp-Verein an — etwa ein Webformular für Eintritte, einen Datenabgleich mit einem Fremdsystem, ein Mitglieder-Login auf der Vereinswebsite oder eine selbst erstellte Auswertung.

Eine API ist eine Schnittstelle, über die andere Programme Daten mit Netxp-Verein austauschen. Damit ein Programm diese Schnittstelle nutzen darf, legen Sie dafür einen API-Client an. Er legt fest,

• wer die Anwendung ist (Client-ID und Secret),
• wie sie sich anmeldet (Zugriffsart),
• wohin sie nach der Anmeldung zurückkehren darf (URIs),
• worauf sie zugreifen darf (Scopes und — beim Zugriff über API-Schlüssel — Benutzerrollen).

Zweck

• Fremdanwendungen (Vereinswebsite, Eigene App, Middleware, Skripte) an Netxp-Verein anbinden
• Pro Anwendungszweck einen eigenen Client mit eigenem Secret und eigenem Rechteumfang betreiben
• Zugriffe gezielt gewähren und bei Bedarf einzeln wieder entziehen

Voraussetzungen

• Netxp-Verein Pro ist gebucht.
• Sie dürfen in der Benutzerliste Benutzer anlegen — dort liegt der Einstieg.
• Das Recht API-Clients (Lesen / Schreiben / Löschen) — es steuert Anzeige, Bearbeitung und Löschung der Clients und wird über die Benutzerrollen vergeben.

Grundbegriffe auf einen Blick

Damit eine Anwendung — z. B. Ihre Vereinswebsite — auf Daten in Netxp-Verein zugreifen darf, muss sie sich vorher anmelden, ähnlich wie ein Besucher am Empfang eines Gebäudes. Diesen „Empfang" übernimmt bei Netxp-Verein der IdentityServer. Die folgenden Begriffe beschreiben, wie diese Anmeldung abläuft.

Begriff	Was ist das?
Client-ID	Der Name, unter dem Ihre Anwendung bei Netxp-Verein bekannt ist. Sie sagt: „Ich bin diese bestimmte Anwendung" — wie ein Benutzername, nur für eine Anwendung statt für eine Person. Netxp-Verein bildet sie automatisch aus dem Anzeigenamen.
Secret	Das Passwort, das zur Client-ID gehört. Erst beides zusammen ermöglicht die Anmeldung, vergleichbar mit Benutzername und Passwort. Die Client-ID darf daher bekannt sein, das Secret muss geheim bleiben.
Token	Ein zeitlich begrenzter Zugangsausweis. Nach der Anmeldung erhält die Anwendung diesen Ausweis und zeigt ihn bei jedem Zugriff vor, statt jedes Mal ihr Passwort zu schicken. Läuft er ab, muss sie sich neu anmelden.
Zugriffsart	Legt fest, wie die Anmeldung abläuft: Meldet sich eine Person im Browser an? Gibt sie ihr Passwort direkt in der Anwendung ein? Oder meldet sich die Anwendung ganz ohne Person an, z. B. für einen nächtlichen / automatischen Abgleich?
Scope	Legt fest, worauf die Anwendung zugreifen darf, z. B. nur auf die E-Mail-Adresse oder auch auf Mitgliederdaten. Wie ein Besucherausweis, der nur bestimmte Türen öffnet.
API-Benutzer	Ein eigener Zugang nur für diese Anwendung, für den Fall, dass sich keine Person anmeldet. Netxp-Verein legt ihn automatisch an; Sie bestimmen nur, was er darf. Er wird nur für die Zugriffsart API Key gebraucht.
API-Schlüssel	Eine lange Zeichenfolge, mit der sich die Anwendung als API-Benutzer anmeldet. Sie ersetzt Benutzername und Passwort und muss deshalb genauso geheim bleiben.

So gehen Sie vor

Ein neuer API-Client wird in dieser Reihenfolge eingerichtet; die einzelnen Reiter sind im Abschnitt Der API-Client im Detail beschrieben.

1. Benutzer → Benutzerliste öffnen.
2. Am Button „Neuer Benutzer" den Pfeil aufklappen und „API-Clients" wählen — die Client-Übersicht öffnet sich.
3. Unten auf „Neuer Client" klicken.
4. Reiter Grunddaten: Anzeigename, Ressource, Typ und Zustimmung festlegen.
5. Reiter Zugriffsart: die benötigten Zugriffsarten ankreuzen.
6. Reiter URIs: bei Login über Browser die Rücksprungadressen eintragen.
7. Reiter Scopes: die benötigten Berechtigungen zuweisen.
8. Reiter API-Benutzer — nur bei Zugriffsart API Key: Benutzerrollen zuweisen.
9. Speichern.
10. Bei einem vertraulichen Client öffnet sich der Reiter Secret: „Neues Secret erzeugen" klicken und das Secret sofort sicher ablegen.
11. Bei Zugriffsart API Key: im Reiter API-Benutzer den API-Schlüssel kopieren und sicher ablegen.
12. Client-ID, Secret und ggf. API-Schlüssel auf gesichertem Weg an die anbindende Anwendung übergeben und einige Minuten warten, bis der Client wirksam ist (siehe Speichern und Wirksamwerden).

Die Client-Übersicht

Die Übersicht listet alle API-Clients des Vereins mit Anzeigename, Client-ID, Secret-Status und Änderungsdatum auf. Sie ist vereinsweit und nicht an einen bestimmten Benutzer gebunden.

Aktion	Vorgehen
Client anlegen	Unten auf „Neuer Client"
Client öffnen	Zeile markieren → „Anzeigen", oder Doppelklick
Client löschen	Zeilen ankreuzen → „Löschen"

Der Client öffnet sich jeweils in einem eigenen Fenster mit den Reitern Grunddaten, Zugriffsart, URIs, Scopes sowie — je nach Einstellung — Secret und API-Benutzer.

Löschen ist endgültig

Gelöschte Clients werden aus der Datenbank entfernt und lassen sich nicht wiederherstellen — es gibt keinen Papierkorb. Alle Anwendungen, die den Client verwenden, können sich danach nicht mehr anmelden. Ein zugehöriger API-Benutzer wird samt API-Schlüssel ebenfalls gelöscht. Zur Sicherheit verlangt nach dem Klick auf „Löschen" ein Rückfrage-Fenster die Eingabe des Sicherheitsworts und listet die betroffenen Clients nochmals auf.

Der API-Client im Detail

Reiter „Grunddaten"

Feld	Bedeutung
Anzeigename	Name der Anwendung, z. B. Website Anmeldeformular. Pflichtangabe.
Client-ID	Wird automatisch aus Vereinsnummer und Anzeigename gebildet — siehe Client-ID.
Ressource*	Der Netxp-Bereich, auf den der Client zugreift — siehe Ressource.
Typ	Vertraulich oder öffentlich — siehe Typ.
Zustimmung	Verhalten des Zustimmungsdialogs — siehe Zustimmung.

* Pflichtangabe

Client-ID

Die Client-ID ist der Name, unter dem Ihre Anwendung bei Netxp-Verein bekannt ist. Sie wird beim Eintippen des Anzeigenamens automatisch gebildet: {Vereinsnummer}_{Anzeigename}, kleingeschrieben, Leerzeichen werden zu Unterstrichen.

Beispiel: Anzeigename Website Anmeldung → Client-ID 1234_website_anmeldung

Anzeigename und Client-ID sind nach dem Speichern gesperrt

Jeder ausgestellte Zugangsausweis (Token) trägt die Client-ID in sich — deshalb lässt sie sich nach dem ersten Speichern nicht mehr ändern. Da sie aus dem Anzeigenamen gebildet wird, ist auch dieser danach gesperrt. Dieselbe Client-ID darf außerdem nicht mehrfach existieren.

Überlegen Sie den Namen daher vorher. Soll ein Client anders heißen, legen Sie einen neuen an und löschen den alten.

Die Client-ID darf bekannt sein

Die Client-ID ist wie ein Benutzername: Sie ist nicht geheim und erscheint z. B. beim Login in der Adresszeile des Browsers. Damit sich niemand Fremdes allein mit der Client-ID als Ihre Anwendung anmelden kann, gehört bei vertraulichen Clients zusätzlich das Secret dazu — wie das Passwort zum Benutzernamen.

Ressource

Die Ressource legt fest, für welchen Netxp-Bereich der API-Client gedacht ist. Davon hängt ab, welche Zugriffsarten angeboten werden, welche Scopes zur Auswahl stehen und ob der Reiter API-Benutzer angezeigt wird.

Ressource	Wofür	Wer meldet sich an?	Reiter API-Benutzer
Mitglieder Online API	Funktionen des Mitgliederportals	Mitglieder mit ihrem Mitgliederzugang	—
Verein Online API	Funktionen der Web-Vereinsverwaltung	Benutzer des Vereins mit ihrem eigenen Login oder der API-Benutzer	✓
Verein API	Die allgemeine Netxp-Verein-API	Benutzer des Vereins mit ihrem eigenen Login, der API-Benutzer oder die Anwendung selbst	✓

Für Vereine des BJV steht zusätzlich die Ressource Verein API BJV zur Verfügung; sie verhält sich wie Verein API.

Ressourcenwechsel entfernt Scopes

Wechseln Sie die Ressource bei einem Client, dem bereits Scopes zugewiesen sind, werden die Scopes, die nur zur bisherigen Ressource gehören, entfernt. Netxp-Verein fragt vorher nach; lehnen Sie ab, bleibt die bisherige Ressource ausgewählt.

Typ

Der Typ beantwortet die Frage, ob die Anwendung ein Secret sicher aufbewahren kann.

Option	Bedeutung	Wann verwenden?
Vertraulich (Server, mit Secret)	Die Anwendung läuft auf einem Server, an dessen Code und Konfiguration niemand von außen herankommt. Sie weist sich mit Client-ID und Secret aus.	Serverdienste, Webanwendungen mit Server-Komponente, Middleware, Skripte auf einem von Ihnen kontrollierten Rechner. Voreinstellung bei Neuanlage.
Öffentlich (App/Browser, ohne Secret)	Die Anwendung läuft direkt auf dem Endgerät des Nutzers (z. B. im Browser oder auf dem Smartphone). Da dort kein Geheimnis sicher hinterlegt werden kann, wird auf ein Secret verzichtet. Netxp-Verein sichert die Anmeldung stattdessen automatisch ohne Secret ab.	Single-Page-Apps im Browser, Smartphone-Apps, Desktop-Anwendungen beim Anwender.

Die Kernfrage zur Unterscheidung

„Läuft die Anwendung auf einem eigenen, geschützten Server – oder direkt auf dem Gerät bzw. im Browser des Nutzers?" Eigener Server → vertraulich · Gerät / Browser des Nutzers → öffentlich

Beim Umschalten auf öffentlich passt sich die Oberfläche automatisch an:

• Client Credentials wird deaktiviert und abgewählt — ohne Secret kann sich die Anwendung nicht selbst ausweisen.
• Der zusätzliche Schutzmechanismus wird eingeschaltet und gesperrt (Haken PKCE erforderlich in den technischen Details).
• Der Reiter Secret wird ausgeblendet. Ein bereits erzeugtes Secret bleibt gespeichert, wird aber nicht mehr verwendet — die Oberfläche weist darauf hin.

Zustimmung

Steuert, ob der angemeldete Nutzer der Anwendung den Zugriff ausdrücklich erlauben muss — bekannt von „Mit Google anmelden": „App X möchte Zugriff auf Ihr Profil — Erlauben / Ablehnen?".

Option	Zustimmungsdialog?	Wer entscheidet?	Wann verwenden?
Ausdrücklich – Nutzer muss zustimmen	Nur beim ersten Mal, danach gemerkt	Der Nutzer	Der sichere Regelfall, vor allem für Anwendungen Dritter. Voreinstellung bei Neuanlage.
Implizit – keine Zustimmung nötig	Nie	Niemand — automatisch erlaubt	Eigene, vollständig vertrauenswürdige Anwendungen des Vereins.
Extern – außerhalb verwaltet	Nie	Vorab, z. B. ein Administrator	Nur, wenn Ihre Integration das ausdrücklich vorsieht. Liegt keine externe Freigabe vor, wird der Zugriff abgelehnt.
Systematisch – bei jeder Anfrage	Bei jeder Anmeldung	Der Nutzer	Besonders schutzbedürftige Zugriffe.

Ohne Benutzeranmeldung keine Zustimmung

Bei Client Credentials und API Key meldet sich kein Mensch an — ein Zustimmungsdialog kommt dort nicht vor. Die Einstellung wirkt praktisch nur bei Login über Browser.

Reiter „Zugriffsart"

Hier kreuzen Sie an, auf welchem Weg sich die Anwendung beim IdentityServer anmelden darf. Jede Zugriffsart ist eine eigene Karte; ausgewählte Karten sind blau hinterlegt.

Zugriffsart	So funktioniert sie	Typischer Einsatz
Login über Browser (Authorization Code)	Der Nutzer wird zum Anmeldefenster von Netxp-Verein weitergeleitet, meldet sich dort an und kehrt zur Anwendung zurück. Die Anwendung sieht das Passwort nie.	Webanwendungen und Apps mit Benutzer-Login — der sichere Standardweg. Voreinstellung bei Neuanlage.
Automatisierter Service-Zugriff (Client Credentials)	Die Anwendung meldet sich mit Client-ID und Secret als sie selbst an — ohne Benutzer.	Server-zu-Server-Anbindungen, nächtliche Abgleiche.
Anmeldung automatisch verlängern (Refresh Token)	Erneuert einen abgelaufenen Zugangsausweis (Token), ohne dass sich der Nutzer neu anmelden muss.	Ergänzt Login über Browser oder Password.
Direkter Login mit Benutzername/Passwort (Password)	Der Nutzer gibt Benutzername und Passwort direkt in der Anwendung ein, die sie an den IdentityServer weiterreicht.	Bestehende Anwendungen ohne Browser-Login — nach Möglichkeit vermeiden.
Zugriff über API-Key (API Key)	Die Anwendung meldet sich mit dem API-Schlüssel des API-Benutzers an und erhält direkt einen Zugangsausweis (Token) — ohne Anmeldefenster.	Skripte, Webformulare, Datenabgleiche, die mit einem fest vergebenen Schlüssel arbeiten.

„Login über Browser" ist vorausgewählt

Bei einem neuen Client ist Login über Browser bereits angekreuzt. Diese Zugriffsart verlangt mindestens eine Redirect-URI. Benötigt Ihre Anwendung nur API Key oder Client Credentials, entfernen Sie den Haken — sonst bricht das Speichern mit einem Hinweis ab.

Password nur in Ausnahmefällen

Beim Ablauf Password sieht die Anwendung das Klartext-Passwort des Nutzers. Das Verfahren gilt deshalb als veraltet. Verwenden Sie für neue Anbindungen mit Benutzer Login über Browser.

Mindestens eine Zugriffsart ist Pflicht

Ohne angekreuzte Zugriffsart lässt sich der Client nicht speichern. Kreuzen Sie nur an, was die Anwendung tatsächlich benötigt.

Welche Zugriffsart ist mit welcher Ressource möglich?

Welche Karten angezeigt werden, richtet sich nach der gewählten Ressource. Nicht passende Karten werden ausgeblendet und ihr Haken entfernt.

Ressource	Login über Browser	Password	API Key	Client Credentials
Mitglieder Online API	✓	✓	—	—
Verein Online API	✓	✓	✓	—
Verein API	✓	✓	✓	✓ ¹

Refresh Token steht immer dann zur Verfügung, wenn Login über Browser oder Password möglich ist.

Wer meldet sich an?

Die Zugriffsart entscheidet auch, wessen Rechte beim Zugriff gelten:

Zugriffsart	Wer meldet sich an?	Welche Rechte gelten?
Login über Browser, Password	Eine Person mit ihrem eigenen Netxp-Verein-Benutzer — bzw. ein Mitglied mit seinem Mitgliederzugang	Die Rechte dieser Person
API Key	Der API-Benutzer des Clients	Die Benutzerrollen im Reiter API-Benutzer
Client Credentials	Ein von Netxp vorgegebener Standardnutzer ¹	Von Netxp vorgegeben

¹ Bei Client Credentials greift die Anwendung über einen von Netxp vorgegebenen Standardnutzer zu, der im Hintergrund liegt und vom Verein weder zur Anmeldung genutzt noch bearbeitet werden kann. Bei Änderungen über diesen Weg ist daher nicht erkennbar, welche Person die Daten geändert hat. Soll das nachvollziehbar bleiben, verwenden Sie eine Zugriffsart mit Benutzeranmeldung (Login über Browser).

Technische Details

Diesen Bereich braucht in der Regel nur, wer die Anwendung technisch einrichtet — Sie können ihn sonst überspringen.

Über den Link „Technische Details anzeigen" klappen Sie die Endpunkte, den Response Type und PKCE auf. Diese Werte setzt Netxp-Verein beim Ankreuzen der Zugriffsarten automatisch; für die meisten Anbindungen müssen Sie hier nichts ändern.

Einstellung	Bedeutung	Wird automatisch gesetzt bei
Endpunkt Authorization	Das Anmeldefenster des IdentityServers.	Login über Browser
Endpunkt Token	Ausgabe der Zugangsausweise (Tokens). Praktisch immer erforderlich.	allen Zugriffsarten außer Refresh Token
Endpunkt Logout	Abmeldung samt Beenden der Sitzung beim IdentityServer — bei mehreren angebundenen Anwendungen auch für alle gleichzeitig. Voraussetzung für Post-Logout-URIs.	—
Endpunkt Revocation	Die Anwendung kann ein Token aktiv sperren lassen, z. B. beim Abmelden des Nutzers. Empfohlen.	—
Response Type code	Nach dem Login wird zunächst nur ein kurzlebiger Code an die Anwendung geliefert, der anschließend im Hintergrund gegen das Token getauscht wird. So durchläuft das Token nie den Browser.	Login über Browser
PKCE erforderlich	Sichert den Code zusätzlich ab: Ein abgefangener Code allein ist nutzlos.	Typ öffentlich (dann nicht abwählbar)

Automatisch gesetzte Haken nicht wieder entfernen

Setzt Netxp-Verein einen Haken beim Ankreuzen einer Zugriffsart selbst, ist er für diesen Ablauf erforderlich. Entfernen Sie ihn wieder, schlägt die Anmeldung der Anwendung fehl.

PKCE ist bei vertraulichen Clients optional, aber empfohlen, sobald Login über Browser verwendet wird.

Wie funktioniert PKCE genau?

Die Anwendung denkt sich vor dem Login ein zufälliges Geheimnis aus und schickt nur dessen „Fingerabdruck" an das Anmeldefenster. Beim späteren Eintausch des Codes gegen das Token muss sie das ursprüngliche Geheimnis vorzeigen. Wer den Code unterwegs abfängt, kennt dieses Geheimnis nicht und erhält kein Token.

„Zusätzlich hinterlegt und unverändert übernommen"

Erscheint dieser Hinweis in den technischen Details, enthält der Client Einstellungen, die diese Oberfläche nicht darstellt — etwa aus einer älteren Konfiguration. Diese Werte bleiben beim Speichern unverändert erhalten. Der Bereich klappt in diesem Fall automatisch auf.

Reiter „URIs"

Hier hinterlegen Sie Rücksprungadressen Ihrer Anwendung: Seiten, zu denen der Nutzer nach der Anmeldung bzw. Abmeldung zurückgeschickt werden darf. Beide Listen werden über das Eingabefeld und „Hinzufügen" gepflegt; zum Entfernen markieren Sie einen Eintrag und klicken „Entfernen".

Liste	Wofür
Redirect-URIs (Rücksprungadresse nach der Anmeldung)	Rücksprung nach erfolgreicher Anmeldung, z. B. https://app.example.de/signin-callback. Nur bei Login über Browser relevant — ohne diese Zugriffsart ist die Liste gesperrt.
Post-Logout-URIs (Rücksprungadresse nach der Abmeldung)	Rücksprung nach der Abmeldung, z. B. zur Startseite. Sinnvoll in Verbindung mit dem Endpunkt Logout.

Der IdentityServer akzeptiert ausschließlich exakt hier eingetragene Adressen. Das verhindert, dass jemand die Anmeldung auf eine fremde Seite umleitet und dort den Code abgreift.

Regeln für beide Listen — Netxp-Verein prüft sie schon beim Hinzufügen:

Regel	Grund
Vollständige Adresse — z. B. https://app.example.de/callback	Teiladressen würden vom IdentityServer stillschweigend verworfen.
https:// ist Pflicht — Ausnahme: localhost für Testzwecke	Über http wäre der Rückweg mitlesbar.
Keine Platzhalter (*)	Jede Adresse wird einzeln eingetragen.
Kein Fragment (#…)	Von OpenID Connect nicht zugelassen.
Kein Komma	Das Komma trennt die gespeicherten Adressen voneinander.

Login über Browser ohne Redirect-URI lässt sich nicht speichern

Ist Login über Browser angekreuzt, muss mindestens eine Redirect-URI eingetragen sein.

Test- und Produktivadresse gemeinsam eintragen

Es können mehrere Adressen hinterlegt werden, z. B. https://app.example.de/callback und https://localhost:5001/callback für die Entwicklung. Entfernen Sie die Testadressen, sobald die Anbindung produktiv ist.

Reiter „Scopes"

Scopes legen fest, worauf die Anwendung mit ihrem Zugangsausweis (Token) zugreifen darf. Während die Zugriffsart beschreibt, wie die Anmeldung abläuft, beschreiben die Scopes, was die Anwendung danach darf — wie ein Besucherausweis, der nur bestimmte Türen öffnet.

Über „Hinzufügen" öffnet sich eine durchsuchbare Auswahlliste (Mehrfachauswahl über die Ankreuzspalte). Angeboten werden nur noch nicht zugewiesene Scopes, und zwar die Standard-Scopes sowie die Scopes der gewählten Ressource. Zum Entfernen markieren Sie die Zeilen im Raster und klicken „Entfernen" — die Rückfrage nennt die betroffenen Scopes namentlich.

Das Raster zeigt je Scope den Anzeigenamen, eine Beschreibung, den technischen Scope-Namen und die Spalte Standard.

Die Spalte „Standard"

Zustand	Wirkung
Zugewiesen, Standard nicht markiert	Die Anwendung darf den Scope anfordern. Tut sie es nicht, ist er im Token nicht enthalten.
Zugewiesen und Standard markiert	Der Scope ist immer im Token enthalten, auch ohne ausdrückliche Anforderung.
Nicht zugewiesen	Der Scope wird abgelehnt, selbst wenn die Anwendung ihn anfordert.

Standard sparsam setzen

Ein als Standard markierter Scope wird immer mitgegeben. Zur Wahrung der Datensicherheit sollte diese Option nur sparsam eingesetzt werden.

Welche Scopes gibt es?

1. Standard-Scopes — bei jeder Ressource verfügbar:

Scope	Anzeigename	Berechtigt zu
openid	OpenID	Grundvoraussetzung für den Login-Nachweis: die Anwendung erfährt, wer angemeldet ist.
profile	Profil	Angaben zur Person des angemeldeten Nutzers, z. B. Name.
email	E-Mail	Die E-Mail-Adresse des angemeldeten Nutzers.
offline_access	Automatische Anmeldung verlängern	Ausgabe eines Refresh Tokens, also Zugriff auch dann, wenn der Nutzer gerade nicht aktiv ist.

offline_access wird automatisch ergänzt

Ist Anmeldung automatisch verlängern (Refresh Token) angekreuzt, fügt Netxp-Verein beim Speichern offline_access selbstständig hinzu — ohne diesen Scope gibt der IdentityServer kein Refresh Token aus.

2. Fach-Scopes — sie bilden die Rechte-Bereiche von Netxp-Verein ab und gehören jeweils zu einer Ressource. Angeboten werden nur die Fach-Scopes der gewählten Ressource.

Welche Fach-Scopes konkret zur Auswahl stehen, hängt von den freigeschalteten Modulen und der Konfiguration Ihres Vereins ab — die Auswahlliste zeigt jeweils den für Sie gültigen Stand mit Anzeigename und Beschreibung.

Nur zuweisen, was gebraucht wird

Klären Sie vor der Zuweisung mit dem Anbieter der Anwendung, welche Scopes sie tatsächlich anfordert. Je weniger Scopes, desto geringer der mögliche Schaden, falls ein Zugangsausweis in falsche Hände gerät.

„Standard-Scopes hinterlegt, die ihm nicht zugewiesen sind"

Diese Meldung beim Öffnen stammt aus Altdaten. Beim nächsten Speichern werden diese Einträge entfernt — Sie müssen nichts weiter tun. Prüfen Sie danach, ob alle benötigten Scopes noch in der Liste stehen.

Reiter „Secret"

Das Secret ist das Passwort, das zur Client-ID gehört. Wie bei einem Benutzerkonto ermöglichen erst beide zusammen die Anmeldung. Während die Client-ID bekannt sein darf, muss das Secret geheim bleiben. Ein vertraulicher Client benötigt es zwingend — ohne Secret wird er vom IdentityServer nicht übernommen.

Der Reiter erscheint nur bei vertraulichen Clients, die bereits gespeichert sind. Nach dem ersten Speichern eines neuen vertraulichen Clients bleibt das Fenster deshalb offen und wechselt direkt hierher.

1. „Neues Secret erzeugen" klicken.
2. Das Secret wird einmalig im Klartext angezeigt.
3. Sofort kopieren und sicher ablegen bzw. in der anbindenden Anwendung hinterlegen.

Das Secret wird nie wieder angezeigt

Nach dem Schließen ist das Secret nicht mehr einsehbar — es liegt am Server nur verschlüsselt vor. Die Oberfläche zeigt danach lediglich „Ein Secret ist gesetzt.".

Es gibt genau ein Secret pro Client. Erzeugen Sie ein neues, wird das bisherige sofort ungültig; alle damit eingerichteten Zugriffe funktionieren erst wieder, wenn Sie das neue Secret überall eingetragen haben. Das lässt sich nicht rückgängig machen.

Vorgehen bei Verdacht auf Missbrauch

Ist ein Secret möglicherweise an Unberechtigte gelangt: neues Secret erzeugen (das alte ist damit ungültig) und in der Anwendung austauschen. Da jeder Client sein eigenes Secret hat, betrifft das nur diese eine Anbindung.

Reiter „API-Benutzer"

Der API-Benutzer ist ein eigener, technischer Zugang dieses Clients. Er wird nur für die Zugriffsart API Key gebraucht: Dort meldet sich keine Person an, sondern die Anwendung selbst — mit dem API-Schlüssel des API-Benutzers. Was sie dabei darf, bestimmen die Benutzerrollen des API-Benutzers.

Wann brauchen Sie den API-Benutzer?

• Zugriffsart API Key angekreuzt → ja: Benutzerrollen zuweisen und den API-Schlüssel abholen.
• Nur Login über Browser, Password oder Client Credentials → nein. Bei Login über Browser und Password melden sich Personen mit ihrem eigenen Benutzer an, und es gelten deren Rechte. Den Reiter können Sie dann unbeachtet lassen.

Der Reiter erscheint, sobald die Ressource Verein Online API oder Verein API gewählt ist. Bei Mitglieder Online API entfällt er — dort melden sich Mitglieder mit ihrem Mitgliederzugang an.

Sie müssen den API-Benutzer nicht selbst anlegen: Netxp-Verein erzeugt ihn beim ersten Speichern automatisch. Einen Benutzernamen oder ein Passwort brauchen Sie dafür nicht. Der API-Benutzer erscheint nicht in der Benutzerliste — Sie verwalten ihn ausschließlich hier.

Benutzerrollen

Die Benutzerrollen bestimmen, auf welche Funktionen und Daten der API-Benutzer zugreifen darf — genau wie bei einem normalen Benutzer.

1. Über „Hinzufügen" eine oder mehrere Benutzerrollen auswählen.
2. Zum Entziehen die Rolle markieren und „Entfernen" klicken.
3. Über „Matrix" sehen Sie, welche Rechte sich aus den Rollen tatsächlich ergeben.
4. Speichern.

Eigene Rolle für den API-Zugriff

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

API-Schlüssel

Den API-Schlüssel erzeugt Netxp-Verein beim ersten Speichern automatisch. Das Fenster bleibt danach offen, wechselt auf diesen Reiter und zeigt den Schlüssel an. Kopieren Sie ihn und legen Sie ihn sicher ab. Über die Schaltfläche „Anzeigen" lässt er sich später erneut abrufen.

Der Schlüssel bleibt gültig, solange der API-Client besteht. Wird der Client gelöscht, werden API-Benutzer und Schlüssel mit gelöscht.

Anmeldung mit dem API-Schlüssel auch im Browser

Mit dem API-Schlüssel kann man sich auch auf der Anmeldeseite von Netxp-Verein anmelden — bei der Zugriffsart Login über Browser, z. B. beim Ausprobieren in der Swagger-Oberfläche. Das gilt für die Ressourcen Verein Online API und Verein API. Bei Mitglieder Online API melden sich Mitglieder immer mit E-Mail-Adresse und Passwort an.

Den API-Schlüssel wie ein Passwort behandeln

Wer den Schlüssel kennt, kann im Rahmen der zugewiesenen Benutzerrollen und Scopes auf Ihre Vereinsdaten zugreifen. Geben Sie ihn ausschließlich auf gesichertem Weg an den vorgesehenen Empfänger weiter — nicht per unverschlüsselter E-Mail oder Chat und nicht im Klartext in Quellcode oder Konfigurationsdateien.

Besteht der Verdacht eines Missbrauchs, löschen Sie den API-Client und legen Sie für die Anwendung einen neuen an — nur so wird der bisherige Schlüssel ungültig.

Speichern und Wirksamwerden

Mit „Speichern" werden alle Reiter gespeichert und das Fenster geschlossen. Es bleibt nur dann offen, wenn noch ein Secret zu erzeugen oder ein neuer API-Schlüssel abzuholen ist.

Änderungen wirken nicht sofort

Alle Änderungen an einem API-Client werden zeitverzögert übernommen — Anlegen, Bearbeiten, ein neues Secret ebenso wie das Löschen. Es dauert oft einige Minuten, bis der Client mit den gespeicherten Einstellungen arbeitet.

Schlägt ein Test unmittelbar nach dem Speichern fehl, warten Sie kurz und wiederholen Sie ihn. Umgekehrt gilt: Ein gelöschter oder eingeschränkter Zugriff kann in dieser Zeitspanne noch funktionieren.

Beim Schließen mit ungespeicherten Änderungen fragt Netxp-Verein nach, ob diese verworfen werden sollen.

Typische Einrichtungen

Einstellung	Skript / Webformular mit API-Schlüssel	Server-zu-Server ohne Benutzer	Website mit Mitglieder-Login	Smartphone- oder Browser-App
Ressource	Verein API	Verein API	Mitglieder Online API	je nach Zweck
Typ	Vertraulich	Vertraulich	Vertraulich	Öffentlich
Zustimmung	Implizit	Implizit	Ausdrücklich	Ausdrücklich
Zugriffsart	API Key	Client Credentials	Login über Browser + Refresh Token	Login über Browser + Refresh Token
Technische Details	automatisch	automatisch, zusätzlich Revocation	automatisch, zusätzlich Logout, Revocation, PKCE	automatisch (PKCE fest gesetzt)
URIs	keine	keine	Redirect-URI https://…/signin-oidc, Post-Logout-URI https://…/signout-callback-oidc	Rückkehradresse der App
Scopes	benötigte Fach-Scopes	benötigte Fach-Scopes	openid, profile, email + benötigte Fach-Scopes	je nach Zweck
Secret	erzeugen	erzeugen	erzeugen	entfällt
Reiter API-Benutzer	Rolle zuweisen, Schlüssel abholen	nicht benötigt	—	—

Was die anbindende Anwendung von Ihnen braucht

• die Client-ID,
• bei vertraulichen Clients das Secret,
• bei Zugriffsart API Key den API-Schlüssel,
• die Scopes, die sie anfordern soll.

Häufige Fehler

„Die angegebenen Clientdaten sind unzureichend."

Beim Speichern fehlt eine Pflichtangabe. Die Meldung nennt die Ursachen, z. B. kein Anzeigename, keine Ressource, keine Zugriffsart oder Login über Browser ohne Redirect-URI.

„Diese Client-ID ist bereits vergeben."

Die Client-ID wird aus Vereinsnummer und Anzeigename gebildet und darf nicht mehrfach existieren. Wählen Sie einen anderen Anzeigenamen — z. B. mit Zusatz v2 oder dem Einsatzzweck.

Gewünschte Zugriffsart fehlt im Reiter „Zugriffsart"

Die Karten richten sich nach der gewählten Ressource — siehe Welche Zugriffsart ist mit welcher Ressource möglich?. Client Credentials ist außerdem bei Typ öffentlich gesperrt.

Anmeldung schlägt mit „invalid redirect_uri" fehl

Die von der Anwendung gemeldete Adresse muss exakt einem Eintrag entsprechen — inklusive Protokoll, Groß-/Kleinschreibung des Pfades und abschließendem /. Vergleichen Sie beides zeichengenau.

Kein Refresh Token trotz angekreuzter Zugriffsart

Prüfen Sie, ob offline_access unter den Scopes steht (wird beim Speichern automatisch ergänzt) und ob die Anwendung diesen Scope bei der Anmeldung tatsächlich anfordert — oder markieren Sie ihn als Standard.

Anmeldung schlägt direkt nach dem Speichern fehl

Gespeicherte Änderungen werden erst nach einigen Minuten aktiv (siehe Speichern und Wirksamwerden). Kurz warten und erneut testen.

API-Zugriff funktioniert plötzlich nicht mehr

Mögliche Ursachen: Das Secret wurde neu erzeugt, der Client wurde gelöscht, oder Benutzerrollen bzw. Scopes wurden geändert.

Zugriff wird trotz gültigem API-Schlüssel verweigert

Prüfen Sie die Benutzerrollen im Reiter API-Benutzer (Schaltfläche „Matrix") und die zugewiesenen Scopes. Der Zugriff ist auf das beschränkt, was beide zusammen erlauben.

Secret oder API-Schlüssel verloren

Ein Secret lässt sich nicht erneut anzeigen: neues erzeugen und in der Anwendung nachtragen — das alte wird dabei ungültig. Den API-Schlüssel rufen Sie im Reiter API-Benutzer über „Anzeigen" erneut ab.

Eintrag „API-Clients" fehlt

Mögliche Ursachen: fehlendes Recht API-Clients (mindestens Lesen, siehe Benutzerrollen), fehlende Berechtigung zum Anlegen von Benutzern, oder Netxp-Verein Pro ist für Ihren Verein nicht gebucht (siehe Vertrag verwalten).

„Die Client-Verwaltung ist nur für Vereinsbenutzer verfügbar."

Die Verwaltung setzt einen Benutzer mit Vereinszuordnung voraus. Melden Sie sich mit einem regulären Benutzer Ihres Vereins an.

Tipps & Hinweise

Ein Client pro Anwendungszweck

Legen Sie nicht einen Sammelclient für alles an, sondern je einen pro Anwendung — Website, App, Middleware. So lassen sich Rechte gezielt zuschneiden und eine einzelne Anbindung abschalten, ohne die anderen zu stören.

Anzeigenamen sprechend wählen

Der Anzeigename ist später nicht mehr änderbar und bestimmt die Client-ID. Bewährt hat sich ein Muster wie Website Anmeldung oder Middleware Beitragsabgleich.

Zugriffe regelmäßig prüfen

Gehen Sie die Client-Liste regelmäßig, mindestens einmal jährlich durch und löschen Sie Clients, deren Anwendung nicht mehr betrieben wird. Prüfen Sie vor dem Löschen, ob der Client wirklich nicht mehr verwendet wird — gelöschte Clients können nicht wiederhergestellt werden.

Verwandte Themen

• Benutzerliste — Einstieg in die Client-Verwaltung
• Benutzerrollen — Rechte des API-Benutzers und das Recht API-Clients
• Netxp-Verein Pro — Voraussetzung für API-Clients
• Zwei-Faktor (2FA) — Absicherung interaktiver Benutzerzugänge
• Ereignisprotokoll — Nachvollziehen von Änderungen
• Schnittstellen (API) — Verbindungsdaten, Schnellstart und Codebeispiele