L'API PSB d'eConnect utilise OAuth 2.0 pour l'authentification. Chaque requête API contient un Bearer token que vous obtenez auprès de l'Identity Server d'eConnect. Ce token est valable une heure et contient toutes les informations dont la PSB a besoin pour déterminer qui vous êtes, au nom de quelle organisation vous travaillez et ce que vous êtes autorisé à faire.

Dans cet article, vous parcourez l'ensemble du processus d'authentification : de la compréhension du modèle d'authentification à la demande et l'utilisation des tokens.

La PSB fonctionne avec quatre couches d'identification. Chaque couche répond à une question différente, et ensemble elles déterminent l'accès à l'API.

Couche 1 : Application (clientId + clientSecret) Identifie le logiciel qui se connecte à la PSB. En règle générale, un partenaire logiciel utilise un seul jeu clientId/clientSecret pour tous ses clients finaux. Cela simplifie l'intégration : les clients finaux ont moins de données techniques à renseigner et le risque d'erreurs de configuration est réduit. Tous les clientIds ont le même scope (ap) et donc les mêmes droits fonctionnels.

Couche 2 : Client final (username + password) Identifie au nom de quelle organisation le travail est effectué. Pour chaque client final, eConnect crée un compte utilisateur PSB, lié à un ou plusieurs partyIds (numéro de chambre de commerce, numéro de TVA, OIN, numéro d'entreprise belge). Avec le flux Resource Owner Password Credentials, vous fournissez un username et un password qui déterminent quelles parties sont accessibles. Avec le flux Client Credentials, cela n'est pas nécessaire car les droits sont directement liés à l'application. Le nom d'utilisateur et le mot de passe sont généralement fournis directement au client final ; le client final les partage ensuite avec l'éditeur du logiciel. Lors de la création d'un compte utilisateur client final au sein de votre propre tenant PSB (par exemple pour l'intégration 4PS Business Central), le mot de passe ne peut pas contenir de caractères spéciaux, à l'exception du point d'exclamation (!).

Couche 3 : Environnement (tenantId) Assure la séparation administrative entre les environnements. Chaque client final reçoit généralement son propre tenant, ce qui garantit une séparation complète des messages, de la configuration et de la journalisation. Certains partenaires logiciels regroupent plusieurs clients finaux au sein d'un seul tenant pour une gestion centralisée ; d'autres choisissent un tenant séparé par client pour un isolement maximal. Les tenants ne peuvent pas être fusionnés, mais les comptes utilisateurs peuvent être modifiés ou étendus.

Couche 4 : Journalisation (subscription key, legacy) Le header Subscription-Key était initialement destiné à l'identification dans les fichiers de logs de l'API. Pour l'API PSB, ce header n'est plus requis. Si vous l'envoyez, la valeur doit être valide. eConnect émet parfois encore des subscription keys car elles permettent de tracer chaque requête vers un partenaire logiciel spécifique dans les logs. Remarque : pour la plateforme eConnect (platform.econnect.eu), la subscription key est toujours requise.

Vous demandez un token en envoyant une requête POST au endpoint /connect/token de l'Identity Server.

C'est le flux recommandé pour les intégrations serveur à serveur. Vous envoyez uniquement votre clientId et votre clientSecret.

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

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

Avec ce flux, vous fournissez également un nom d'utilisateur et un mot de passe. C'est utile lorsque les droits sont liés à un utilisateur final spécifique.

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

grant_type=password
&client_id=votre-client-id
&client_secret=votre-client-secret
&username=votre-nom-utilisateur
&password=votre-mot-de-passe
&scope=ap

En cas de requête réussie, vous recevez un objet JSON contenant l'access token :

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

Le champ expires_in indique le nombre de secondes de validité du token. La valeur par défaut est de 3600 secondes (1 heure).

Incluez le Bearer token dans le header Authorization de chaque requête API à la PSB :

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

La PSB valide le token à chaque requête. Si le token est invalide ou expiré, vous recevez une réponse 401 Unauthorized.

Un Bearer token est valable 3600 secondes. Après son expiration, vous devez demander un nouveau token via le même endpoint /connect/token. Il n'existe pas de flux de rafraîchissement séparé : vous répétez simplement la demande de token.

En pratique, il est préférable de demander un nouveau token peu avant l'expiration de l'actuel, par exemple après 3500 secondes. Cela évite qu'un appel API échoue à cause d'un token expiré alors que la requête est en transit.

1. Token demandé                → valable jusqu'à t+3600s
2. Après ~3500s : nouveau token → ancien token encore ~100s valable
3. Basculer vers le nouveau token

Stockez le token dans votre application et réutilisez-le pour plusieurs requêtes. Ne demandez pas un nouveau token à chaque appel API, car cela génère une charge inutile sur l'Identity Server.

Par défaut, un partenaire logiciel utilise un seul jeu clientId/clientSecret pour tous ses clients finaux. Dans certaines situations, il est judicieux d'utiliser plusieurs jeux :

• Séparer test et production. Utilisez un clientId distinct pour l'environnement d'acceptation (accp-identity.econnect.eu) et pour la production (identity.econnect.eu). Cela empêche que des identifiants de test se retrouvent accidentellement en production.
• Installations on-premise. Si le logiciel s'exécute chez le client final et que celui-ci a accès à la configuration, un clientSecret partagé peut représenter un risque de sécurité. Avec un clientId distinct par client, vous limitez les dégâts en cas de fuite d'identifiants.
• Droits séparés par intégration. Si vous développez plusieurs applications autonomes nécessitant chacune des fonctionnalités API différentes (par exemple un module de facturation et un module de commandes), vous pouvez utiliser un clientId propre par application avec uniquement les droits nécessaires.

La révocation d'un clientSecret n'affecte que le clientId correspondant. Les autres clients ou intégrations ne sont pas impactés.

Si vous recevez un 401 lors d'un appel API à la PSB, vérifiez d'abord si le token est encore valide. Dans la plupart des cas, il a expiré et il suffit de demander un nouveau token.

Le diagramme ci-dessous montre comment une application demande un token à l'Identity Server, puis utilise ce token pour appeler l'API PSB.

La référence API complète, incluant tous les endpoints et les formats de requête/réponse, est disponible dans la documentation Swagger interactive.