De PSB API van eConnect gebruikt OAuth 2.0 voor authenticatie. Elk API-verzoek bevat een Bearer token dat je opvraagt bij de eConnect Identity Server. Dit token is een uur geldig en bevat alle informatie die de PSB nodig heeft om te bepalen wie je bent, namens welke organisatie je werkt en wat je mag doen.

In dit artikel doorloop je het volledige authenticatieproces: van het begrijpen van het authenticatiemodel tot het aanvragen en gebruiken van tokens.

De PSB werkt met vier lagen van identificatie. Elke laag beantwoordt een andere vraag, en samen bepalen ze de toegang tot de API.

Laag 1: Applicatie (clientId + clientSecret) Identificeert de software die verbinding maakt met de PSB. Doorgaans gebruikt een softwarepartner één set clientId/clientSecret voor al zijn eindklanten. Dit vereenvoudigt de onboarding: eindklanten hoeven minder technische gegevens in te vullen en de kans op configuratiefouten is kleiner. Alle clientId's hebben dezelfde scope (ap) en dus dezelfde functionele rechten.

Laag 2: Eindklant (username + password) Identificeert namens welke organisatie er wordt gewerkt. Per eindklant maakt eConnect een PSB-gebruikersaccount aan, gekoppeld aan een of meerdere partyIds (KVK-nummer, BTW-nummer, OIN, Belgisch ondernemingsnummer). Bij de Resource Owner Password Credentials-flow geef je een username en password mee die bepalen welke party's toegankelijk zijn. Bij de Client Credentials-flow is dit niet nodig omdat de rechten direct aan de applicatie zijn gekoppeld. De username en password worden doorgaans direct aan de eindklant verstrekt; de eindklant deelt ze zelf met de softwareleverancier.

Laag 3: Omgeving (tenantId) Biedt administratieve scheiding tussen omgevingen. Elke eindklant krijgt doorgaans een eigen tenant, wat zorgt voor volledige scheiding van berichten, configuratie en logging. Sommige softwarepartners plaatsen meerdere eindklanten binnen één tenant voor centraal beheer; andere kiezen voor een aparte tenant per klant voor maximale isolatie. Tenants kunnen niet worden samengevoegd, maar gebruikersaccounts kunnen wel worden aangepast of uitgebreid.

Laag 4: Logging (subscription key, legacy) De Subscription-Key header was oorspronkelijk bedoeld voor identificatie in API-logbestanden. Voor de PSB API is deze header niet meer vereist. Als je hem meestuurt, moet de waarde wel geldig zijn. eConnect geeft de subscriptionkey soms nog uit omdat deze bij elk request in logs herleidbaar is naar een specifieke softwarepartner. Let op: voor het eConnect-platform (platform.econnect.eu) is de subscriptionkey nog wel vereist.

Je vraagt een token aan door een POST-verzoek te sturen naar het /connect/token-endpoint van de Identity Server.

Dit is de aanbevolen flow voor server-naar-server integraties. Je stuurt alleen je clientId en clientSecret mee.

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

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

Bij deze flow geef je ook een gebruikersnaam en wachtwoord mee. Dit is nuttig wanneer de rechten aan een specifieke eindgebruiker zijn gekoppeld.

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

grant_type=password
&client_id=jouw-client-id
&client_secret=jouw-client-secret
&username=jouw-gebruikersnaam
&password=jouw-wachtwoord
&scope=ap

Bij een succesvolle aanvraag ontvang je een JSON-object met daarin het access token:

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

Het veld expires_in geeft aan hoeveel seconden het token geldig is. Standaard is dat 3600 seconden (1 uur).

Stuur het Bearer token mee in de Authorization-header bij elk API-verzoek aan de PSB:

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

De PSB valideert het token bij elk verzoek. Als het token ongeldig of verlopen is, ontvang je een 401 Unauthorized-response.

Een Bearer token is 3600 seconden geldig. Na het verlopen moet je een nieuw token aanvragen via hetzelfde /connect/token-endpoint. Er is geen aparte refresh-flow: je herhaalt simpelweg het token-aanvraagverzoek.

In de praktijk kun je het beste een nieuw token aanvragen kort voordat het huidige verloopt, bijvoorbeeld na 3500 seconden. Zo voorkom je dat een API-aanroep faalt door een verlopen token terwijl het verzoek onderweg is.

1. Token aangevraagd          → geldig tot t+3600s
2. Na ~3500s: nieuw token      → oud token nog ~100s geldig
3. Wissel over naar nieuw token

Sla het token op in je applicatie en hergebruik het voor meerdere verzoeken. Vraag niet bij elk API-verzoek een nieuw token aan, want dat leidt tot onnodige belasting van de Identity Server.

Standaard gebruikt een softwarepartner één set clientId/clientSecret voor alle eindklanten. In een aantal situaties is het verstandig om meerdere sets te gebruiken:

• Test en productie gescheiden houden. Gebruik een apart clientId voor de acceptatieomgeving (accp-identity.econnect.eu) en voor productie (identity.econnect.eu). Zo voorkom je dat testcredentials per ongeluk in productie terechtkomen.
• On-premise installaties. Als de software bij de eindklant draait en de klant toegang heeft tot de configuratie, kan een gedeeld clientSecret een beveiligingsrisico zijn. Met een apart clientId per klant beperk je de schade als credentials uitlekken.
• Gescheiden rechten per integratie. Als je meerdere losse applicaties bouwt die elk andere API-functionaliteit nodig hebben (bijvoorbeeld een factuurmodule en een ordermodule), kun je per applicatie een eigen clientId gebruiken met alleen de benodigde rechten.

Het intrekken van een clientSecret heeft alleen effect op het bijbehorende clientId. Andere klanten of integraties worden daardoor niet geraakt.

Als je een 401 ontvangt bij een API-aanroep aan de PSB, controleer dan eerst of het token nog geldig is. In de meeste gevallen is het verlopen en volstaat het aanvragen van een nieuw token.

Het onderstaande diagram toont hoe een applicatie een token opvraagt bij de Identity Server en dat token vervolgens gebruikt om de PSB API aan te roepen.

De volledige API-referentie, inclusief alle endpoints en request-/responseformaten, vind je in de interactieve Swagger-documentatie.