Die PSB API von eConnect verwendet OAuth 2.0 zur Authentifizierung. Jede API-Anfrage enthält ein Bearer Token, das Sie beim eConnect Identity Server anfordern. Dieses Token ist eine Stunde gültig und enthält alle Informationen, die die PSB benötigt, um festzustellen, wer Sie sind, im Namen welcher Organisation Sie arbeiten und was Sie tun dürfen.

In diesem Artikel durchlaufen Sie den vollständigen Authentifizierungsprozess: vom Verständnis des Authentifizierungsmodells bis zur Anforderung und Nutzung von Tokens.

Die PSB arbeitet mit vier Identifikationsebenen. Jede Ebene beantwortet eine andere Frage, und zusammen bestimmen sie den Zugang zur API.

Ebene 1: Anwendung (clientId + clientSecret) Identifiziert die Software, die sich mit der PSB verbindet. Üblicherweise verwendet ein Softwarepartner ein einzelnes Set clientId/clientSecret für alle seine Endkunden. Das vereinfacht das Onboarding: Endkunden müssen weniger technische Daten ausfüllen und die Wahrscheinlichkeit von Konfigurationsfehlern ist geringer. Alle clientIds haben denselben Scope (ap) und damit dieselben funktionalen Berechtigungen.

Ebene 2: Endkunde (username + password) Identifiziert, im Namen welcher Organisation gearbeitet wird. Für jeden Endkunden erstellt eConnect ein PSB-Benutzerkonto, das mit einer oder mehreren partyIds verknüpft ist (Handelskammernummer, Umsatzsteuer-ID, OIN, belgische Unternehmensnummer). Beim Resource Owner Password Credentials-Flow geben Sie einen username und ein password an, die bestimmen, auf welche Parties zugegriffen werden kann. Beim Client Credentials-Flow ist dies nicht erforderlich, da die Berechtigungen direkt mit der Anwendung verknüpft sind. Benutzername und Passwort werden üblicherweise direkt dem Endkunden bereitgestellt; der Endkunde teilt sie dann selbst mit dem Softwareanbieter. Beim Anlegen eines Endkunden-Benutzerkontos innerhalb des eigenen PSB-Tenants (zum Beispiel für die 4PS Business Central-Integration) darf das Passwort keine Sonderzeichen enthalten, mit Ausnahme des Ausrufezeichens (!).

Ebene 3: Umgebung (tenantId) Bietet administrative Trennung zwischen Umgebungen. Jeder Endkunde erhält in der Regel einen eigenen Tenant, was eine vollständige Trennung von Nachrichten, Konfiguration und Logging gewährleistet. Einige Softwarepartner platzieren mehrere Endkunden innerhalb eines einzigen Tenants für eine zentrale Verwaltung; andere wählen einen separaten Tenant pro Kunde für maximale Isolation. Tenants können nicht zusammengeführt werden, aber Benutzerkonten können angepasst oder erweitert werden.

Ebene 4: Logging (Subscription Key, Legacy) Der Subscription-Key-Header war ursprünglich zur Identifikation in API-Logdateien gedacht. Für die PSB API ist dieser Header nicht mehr erforderlich. Wenn Sie ihn mitsenden, muss der Wert gültig sein. eConnect gibt den Subscription Key manchmal noch aus, da er bei jeder Anfrage in den Logs einem bestimmten Softwarepartner zugeordnet werden kann. Hinweis: Für die eConnect-Plattform (platform.econnect.eu) ist der Subscription Key weiterhin erforderlich.

Sie fordern ein Token an, indem Sie eine POST-Anfrage an den /connect/token-Endpoint des Identity Servers senden.

Dies ist der empfohlene Flow für Server-zu-Server-Integrationen. Sie senden nur Ihre clientId und Ihr clientSecret.

POST /connect/token HTTP/1.1
Host: identity.econnect.eu
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
&client_id=ihre-client-id
&client_secret=ihr-client-secret
&scope=ap

Bei diesem Flow geben Sie zusätzlich einen Benutzernamen und ein Passwort an. Das ist sinnvoll, wenn die Berechtigungen an einen bestimmten Endbenutzer gebunden sind.

POST /connect/token HTTP/1.1
Host: identity.econnect.eu
Content-Type: application/x-www-form-urlencoded

grant_type=password
&client_id=ihre-client-id
&client_secret=ihr-client-secret
&username=ihr-benutzername
&password=ihr-passwort
&scope=ap

Bei einer erfolgreichen Anfrage erhalten Sie ein JSON-Objekt mit dem Access Token:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_in": 3600,
  "token_type": "Bearer",
  "scope": "ap"
}

Das Feld expires_in gibt an, wie viele Sekunden das Token gültig ist. Standardmäßig sind das 3600 Sekunden (1 Stunde).

Senden Sie das Bearer Token im Authorization-Header bei jeder API-Anfrage an die PSB mit:

GET /api/v1/me HTTP/1.1
Host: psb.econnect.eu
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...

Die PSB validiert das Token bei jeder Anfrage. Wenn das Token ungültig oder abgelaufen ist, erhalten Sie eine 401 Unauthorized-Antwort.

Ein Bearer Token ist 3600 Sekunden gültig. Nach dem Ablauf müssen Sie ein neues Token über denselben /connect/token-Endpoint anfordern. Es gibt keinen separaten Refresh-Flow: Sie wiederholen einfach die Token-Anfrage.

In der Praxis empfiehlt es sich, ein neues Token kurz vor dem Ablauf des aktuellen anzufordern, beispielsweise nach 3500 Sekunden. So verhindern Sie, dass ein API-Aufruf aufgrund eines abgelaufenen Tokens fehlschlägt, während die Anfrage unterwegs ist.

1. Token angefordert            → gültig bis t+3600s
2. Nach ~3500s: neues Token     → altes Token noch ~100s gültig
3. Auf neues Token umschalten

Speichern Sie das Token in Ihrer Anwendung und verwenden Sie es für mehrere Anfragen wieder. Fordern Sie nicht bei jedem API-Aufruf ein neues Token an, da dies den Identity Server unnötig belastet.

Standardmäßig verwendet ein Softwarepartner ein einzelnes Set clientId/clientSecret für alle Endkunden. In einigen Situationen ist es sinnvoll, mehrere Sets zu verwenden:

• Test und Produktion trennen. Verwenden Sie eine separate clientId für die Abnahmeumgebung (accp-identity.econnect.eu) und für die Produktion (identity.econnect.eu). So verhindern Sie, dass Testzugangsdaten versehentlich in der Produktion landen.
• On-Premise-Installationen. Wenn die Software beim Endkunden läuft und der Kunde Zugang zur Konfiguration hat, kann ein geteiltes clientSecret ein Sicherheitsrisiko darstellen. Mit einer separaten clientId pro Kunde begrenzen Sie den Schaden, falls Zugangsdaten kompromittiert werden.
• Getrennte Berechtigungen pro Integration. Wenn Sie mehrere eigenständige Anwendungen entwickeln, die jeweils unterschiedliche API-Funktionalität benötigen (beispielsweise ein Rechnungsmodul und ein Bestellmodul), können Sie pro Anwendung eine eigene clientId mit nur den erforderlichen Berechtigungen verwenden.

Das Widerrufen eines clientSecret betrifft nur die zugehörige clientId. Andere Kunden oder Integrationen sind davon nicht betroffen.

Wenn Sie einen 401 bei einem API-Aufruf an die PSB erhalten, überprüfen Sie zunächst, ob das Token noch gültig ist. In den meisten Fällen ist es abgelaufen und es genügt, ein neues Token anzufordern.

Das folgende Diagramm zeigt, wie eine Anwendung ein Token beim Identity Server anfordert und dieses Token anschließend für Aufrufe an die PSB API verwendet.

Die vollständige API-Referenz, einschließlich aller Endpoints und Request-/Response-Formate, finden Sie in der interaktiven Swagger-Dokumentation.