The eConnect PSB API uses OAuth 2.0 for authentication. Every API request includes a Bearer token that you obtain from the eConnect Identity Server. This token is valid for one hour and contains all the information the PSB needs to determine who you are, on behalf of which organisation you are working and what you are allowed to do.

In this article you will walk through the full authentication process: from understanding the authentication model to requesting and using tokens.

The PSB works with four layers of identification. Each layer answers a different question, and together they determine access to the API.

Layer 1: Application (clientId + clientSecret) Identifies the software connecting to the PSB. Typically, a software partner uses a single set of clientId/clientSecret for all their end customers. This simplifies onboarding: end customers need to fill in fewer technical details and the chance of configuration errors is smaller. All clientIds have the same scope (ap) and therefore the same functional permissions.

Layer 2: End customer (username + password) Identifies on behalf of which organisation work is being done. For each end customer, eConnect creates a PSB user account linked to one or more partyIds (Chamber of Commerce number, VAT number, OIN, Belgian enterprise number). In the Resource Owner Password Credentials flow you provide a username and password that determine which parties are accessible. In the Client Credentials flow this is not needed because the permissions are linked directly to the application. The username and password are typically provided directly to the end customer; the end customer then shares them with the software vendor.

Layer 3: Environment (tenantId) Provides administrative separation between environments. Each end customer typically receives their own tenant, ensuring complete separation of messages, configuration and logging. Some software partners place multiple end customers within a single tenant for centralised management; others choose a separate tenant per customer for maximum isolation. Tenants cannot be merged, but user accounts can be modified or extended.

Layer 4: Logging (subscription key, legacy) The Subscription-Key header was originally intended for identification in API log files. For the PSB API this header is no longer required. If you do send it, the value must be valid. eConnect sometimes still issues subscription keys because they are traceable to a specific software partner in every request log. Note: for the eConnect platform (platform.econnect.eu) the subscription key is still required.

You request a token by sending a POST request to the /connect/token endpoint of the Identity Server.

This is the recommended flow for server-to-server integrations. You only send your clientId and clientSecret.

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

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

In this flow you also provide a username and password. This is useful when permissions are tied to a specific end user.

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

grant_type=password
&client_id=your-client-id
&client_secret=your-client-secret
&username=your-username
&password=your-password
&scope=ap

On a successful request you receive a JSON object containing the access token:

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

The expires_in field indicates how many seconds the token is valid. The default is 3600 seconds (1 hour).

Include the Bearer token in the Authorization header with every API request to the PSB:

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

The PSB validates the token on every request. If the token is invalid or expired, you receive a 401 Unauthorized response.

A Bearer token is valid for 3600 seconds. After it expires you must request a new token via the same /connect/token endpoint. There is no separate refresh flow: you simply repeat the token request.

In practice it is best to request a new token shortly before the current one expires, for example after 3500 seconds. This prevents an API call from failing due to an expired token while the request is in transit.

1. Token requested             → valid until t+3600s
2. After ~3500s: new token     → old token still valid for ~100s
3. Switch to new token

Store the token in your application and reuse it for multiple requests. Do not request a new token for every API call, as this puts unnecessary load on the Identity Server.

By default a software partner uses a single set of clientId/clientSecret for all end customers. In a number of situations it makes sense to use multiple sets:

• Keeping test and production separate. Use a separate clientId for the acceptance environment (accp-identity.econnect.eu) and for production (identity.econnect.eu). This prevents test credentials from accidentally ending up in production.
• On-premise installations. If the software runs at the end customer's location and the customer has access to the configuration, a shared clientSecret can be a security risk. With a separate clientId per customer you limit the damage if credentials are leaked.
• Separate permissions per integration. If you are building multiple standalone applications that each need different API functionality (for example an invoicing module and an order module), you can use a separate clientId per application with only the required permissions.

Revoking a clientSecret only affects the associated clientId. Other customers or integrations are not impacted.

If you receive a 401 on an API call to the PSB, first check whether the token is still valid. In most cases it has expired and requesting a new token is all that is needed.

The diagram below shows how an application requests a token from the Identity Server and then uses that token to call the PSB API.

The full API reference, including all endpoints and request/response formats, can be found in the interactive Swagger documentation.