Filing REST API Authentication

Introduction

The Filing REST API enables the automated submission of reports to SBR Nexus. To ensure the security and reliability of these submissions, the API supports two different authentication methods.

The authentication method to use depends on how the software integrates with the Filing REST API.

OAuth 2.0 in combination with eHerkenning is intended for applications acting on behalf of an end user. The user authenticates through eHerkenning and explicitly grants the application permission to act on their behalf when calling the Filing REST API. The application subsequently receives an OAuth Access Token that can be used to access the API.
PKIoverheid (PKIo) certificate authentication is intended for server-to-server integrations where no interactive user is present. The application authenticates itself using a valid PKIoverheid client certificate through Mutual TLS (mTLS). Because no user signs in, the application must explicitly identify the user or organization on whose behalf it is acting with every API request.

Depending on the chosen integration, one of these authentication methods is used.

Next step

Once the authentication method for your integration has been determined, please refer to the API Documentation for a description of the available API calls, request formats, and response formats.

API Documentation: https://support.sbrnexus.nl/hc/nl/articles/360014653620-API-documentatie-om-je-software-te-koppelen-met-Aanleveren-Portaal-voorheen-MDMB

Supported Authentication Methods

Authentication Method	Intended Use	Authentication	User Identification
OAuth 2.0 + eHerkenning	Applications acting on behalf of an end user	OAuth 2.0 Authorization Code Flow using a Bearer Access Token	Through the authenticated user (eHerkenning)
PKIoverheid Certificate (Mutual TLS)	Server-to-server integrations (Trusted Applications)	Mutual TLS (mTLS) using a valid PKIoverheid client certificate	Through the `X-External-Entity-Identification` HTTP header

Authentication Methods Summary

OAuth 2.0 + eHerkenning

Use OAuth when an end user needs to authenticate and explicitly grants the application permission to act on their behalf.

Characteristics

End user authenticates using eHerkenning
User grants consent to the application
API requests use Bearer Access Tokens
Refresh Tokens are supported
Suitable for interactive applications

PKIoverheid (Mutual TLS)

Use PKIoverheid certificates for server-to-server integrations where no interactive user is involved.

Characteristics

Authentication through Mutual TLS (mTLS)
No Bearer Access Token required
Authentication is performed during the TLS handshake
The end user is identified through an HTTP header
Suitable for Trusted Applications

OAuth 2.0 with eHerkenning

Overview

The Filing REST API supports the OAuth 2.0 Authorization Code Flow.

This allows an end user to securely authenticate through eHerkenning and grant an application permission to act on their behalf when calling the Filing REST API.

After successful authentication, the application receives an Access Token that can be used to call the API.

OAuth Endpoints

Environment	Base URL
Test	https://test-aanleverenapi.sbrnexus.nl
Acceptance	https://acc-aanleverenapi.sbrnexus.nl
Production	https://aanleverenapi.sbrnexus.nl

The Authorization Endpoint and Token Endpoint are available under the selected environment.

Step 1 - Client Registration

Before OAuth can be used, an OAuth Client must be registered.

The following information is required:

Property	Description
Application Name	Name of the application performing the authentication
Redirect URI(s)	URI to which the user is redirected after authentication
Environment	Test, Acceptance or Production

After registration, SBR Nexus provides:

Client ID
Client Secret

These credentials are required to obtain Access Tokens.

Step 2 - Authorization Request

The application redirects the user to the Authorization Endpoint using the following format (example for a test client):

[base]/auth/realms/mdmb/protocol/openid-connect/auth?response_type=code&client_id=oauth-test-client&redirect_uri=[redirect-uri]&state=[state]&scope=offline_access

Parameters

Parameter	Required	Description
response_type	Yes	Always `code`
client_id	Yes	Client ID of the application
redirect_uri	Yes	Registered redirect URI
state	No	Used to protect against CSRF attacks
scope	No	Use `offline_access` when Refresh Tokens are required

Step 3 - Sign in with eHerkenning

The user is redirected to the eHerkenning sign-in page.

After successful authentication:

the user is authenticated through eHerkenning;
the requested permissions are displayed;
the user can grant the application permission to act on their behalf.

Once consent has been granted, the user is redirected back to the registered Redirect URI.

The application receives:

an Authorization Code
the State parameter (if provided)

Example

[redirect-uri]?code=[authorization-code]&state=[state]

Step 4 - Obtain an Access Token

The application exchanges the Authorization Code for an Access Token by calling the Token Endpoint.

POST

[base]/auth/realms/mdmb/protocol/openid-connect/token

The request body must contain:

grant_type=authorization_code

code=[authorization-code]

redirect_uri=[redirect-uri]

client_id=oauth-test-client

client_secret=[client-secret]

The Filing REST API returns a JSON object containing the OAuth tokens.

Response

{
    "access_token": "[access-token]",
    "expires_in": 300,
    "not-before-policy": 1651679326,
    "refresh_token": "[refresh-token]",
    "refresh_expires_in": 0,
    "scope": "offline_access mdmb",
    "session_state": "[session-state]",
    "token_type": "Bearer"
}

Step 5 - Calling the Filing REST API

Once an Access Token has been obtained, it can be used to call the Filing REST API.

Include the following HTTP header with every request:

Authorization: Bearer <access-token>

Example

POST https://test-aanleverenapi.sbrnexus.nl/api/reports

Authorization: Bearer eyJhbGc...

Step 6 - Refreshing an Access Token

An Access Token can be used immediately after it has been issued and is valid for a limited period of time.

When the Access Token expires, a new Access Token can be requested by calling the Token Endpoint using the Refresh Token.

If the user granted offline access, the Refresh Token can be used indefinitely as long as it is used at least once every 30 days. Otherwise, the Refresh Token also has a limited lifetime.

The request body must contain:

grant_type=refresh_token

refresh_token=[refresh-token]

redirect_uri=[redirect-uri]

client_id=oauth-test-client

client_secret=[client-secret]

The response has the same format as the response returned when obtaining a new Access Token.

Terms and Conditions

Before processing an API request, the Filing REST API verifies whether the user has accepted the latest version of the Terms and Conditions.

If the latest Terms and Conditions have not been accepted, the API returns:

HTTP 403 Forbidden

The user must sign in again and accept the latest Terms and Conditions before API requests can be processed.

PKIoverheid Certificate (Mutual TLS)

Overview

In addition to OAuth 2.0, the Filing REST API supports authentication using Mutual TLS (mTLS) with a PKIoverheid client certificate.

This authentication method is intended for Trusted Applications that submit reports without the involvement of an interactive end user. The application authenticates itself using a valid PKIoverheid client certificate during the TLS handshake.

Unlike OAuth 2.0, no user authentication takes place and no Bearer Access Token is used. Instead, the identity of the user or organization on whose behalf the application is acting must be explicitly included in each API request using an HTTP header.

How Mutual TLS (mTLS) Works

During the TLS handshake, both the client and the Filing REST API present a valid certificate.

The connection is established only if:

the client certificate is valid;
the Filing REST API certificate is trusted;
the certificate chain is complete and valid;
the certificate has not expired;
the certificate has not been revoked.

If any of these validation checks fail, the TLS connection is rejected and the API request will not be processed.

The APIs use a Private Root CA certificate that is not trusted by default. To establish a successful TLS connection, this certificate must be explicitly added to the trust store of the calling application.

The certificate is available from:

https://cert.pkioverheid.nl/

under:

Staat der Nederlanden Private Root CA - G1

PKIo Endpoints

Use the following endpoints when authenticating with Mutual TLS.

Environment	Base URL
Test	https://test-aanleverenapi-pki.sbrnexus.nl
Acceptance	https://acc-aanleverenapi-pki.sbrnexus.nl
Production	https://aanleverenapi-pki.sbrnexus.nl

Important

These endpoints only support authentication using a PKIoverheid client certificate. OAuth 2.0 Bearer Tokens are not supported on these endpoints.

User Identification

Since no user signs in when using Mutual TLS, the application must explicitly identify the user and organization on whose behalf it is acting with every API request.

This is done using the following HTTP header:

X-External-Entity-Identification

The value of this header must be a Base64-encoded JSON document.

The calling application is responsible for ensuring that the supplied identification information is correct.

JSON Structure

The JSON document must contain the identification details of the user on whose behalf the application is acting.

{
  "firstName": "Piet",
  "familyName": "Postbus",
  "email": "Piet.Postbus@example.com",
  "organizationName": "Example Org",
  "organizationCocNumber": "00000012"
}

Required Fields

Field	Description
firstName	User's first name
familyName	User's last name
email	User's email address
organizationName	Name of the organization
organizationCocNumber	Chamber of Commerce registration number of the organization

Base64 Encoding

Before the identification data can be included in the HTTP header, the JSON document must be encoded using Base64.

Example:

JSON

{
  "firstName": "Piet",
  "familyName": "Postbus",
  "email": "Piet.Postbus@example.com",
  "organizationName": "Example Org",
  "organizationCocNumber": "00000012"
}

Base64

ew0KICAgICJmaXJzdE5hbWUiOiAiUGlldCIsDQogICAgImZhbWlseU5hbWUiOiAiUG9zdGJ1cyIsDQogICAgImVtYWlsIjogIlBpZXQuUG9zdGJ1c0BleGFtcGxlLmNvbSIsDQogICAgIm9yZ2FuaXphdGlvbk5hbWUiOiAiRXhhbXBsZSBPcmciLA0KICAgICJvcmdhbml6YXRpb25Db2NOdW1iZXIiOiAiMDAwMDAwMTIiDQp9

The encoded value must be included in the request header.

X-External-Entity-Identification: ew0KICAgICJ...

Authentication in Postman

When testing the Filing REST API with Postman, configure a client certificate.

Navigate to:

Settings → Certificates

Configure the following:

Host: test-aanleverenapi-pki.sbrnexus.nl
Port: 443
PKIoverheid client certificate (.p12, .pfx or .pem)
Private key (if applicable)

Postman automatically presents the client certificate during the TLS handshake.

Authentication in the API

When using Mutual TLS, no Authorization header is included.

Authentication is performed entirely during the TLS handshake.

The API request therefore only contains the functional request headers, for example:

X-External-Entity-Identification: <Base64 encoded JSON>

Content-Type: multipart/form-data

Important

Do not include an Authorization: Bearer header when using PKIoverheid (Mutual TLS). Authentication is performed exclusively by presenting the PKIoverheid client certificate during the TLS handshake.