Certificate requirements and examples

Access to Ons API requires a TLS client certificate signed by our Certificate Authority. A certificate can cover a supplier, a connector, or one customer environment. Access to a customer environment still requires approved consent for a connector version.

Setting up API access
See Setting up API access for certificate scopes, common name formats, CSR example commands and the request process.

CSR requirements

Use an RSA key of at least 4096 bits. See Setting up API access for the required CSR content and example commands for each scope.

If you use a tool other than OpenSSL (for example, BouncyCastle library) to generate a CSR, make sure to use the most recent version of that tool. Older versions may generate invalid CSRs that cannot be signed by us.

Technical Details

TLS

• The minimum TLS version is 1.2.
• The framework you are using must send an SNI extension along with the TLS handshake.

Valid ciphers
Any of the following ciphers can be used:

• ECDHE-ECDSA-AES256-GCM-SHA384
• ECDHE-ECDSA-AES128-GCM-SHA256
• ECDHE-ECDSA-CHACHA20-POLY1305
• ECDHE-RSA-AES256-GCM-SHA384
• ECDHE-RSA-AES128-GCM-SHA256
• ECDHE-RSA-CHACHA20-POLY1305
• DHE-RSA-AES256-GCM-SHA384
• DHE-RSA-AES128-GCM-SHA256

CA Chain
If your framework, platform, or development language requires the full CA chain, it can be obtained here:

• Production CA chain
• Staging CA chain
• Development CA chain

Legacy (No longer issues new certificates)

• Production CA chain (signed before 02-09-2025)
• Staging CA chain (signed before 28-08-2025)
• Development CA chain (signed before 20-08-2025)

Certificate Testing

You can test the certificate by making a GET request to the /ping endpoint on Ons API. Use the URL corresponding to the environment for which the certificate is intended; see also: API properties.

• Example: GET https://api-development.ons.io/ping
• Result:
  • 200: The certificate works.
  • 403: The certificate does not work in combination with the provided URL.

If you are testing with curl on Windows, make sure to use a recent version of curl. Often version 7.55.1 is installed, which does not handle client certificates well.

---