In order to authenticate requests to the Numeral API, Numeral enforces two levels of authentication:
- A first level based on IP whitelisting or mutual TLS (mTLS) authentication
- A second level based on the API key
1. IP whitelisting and mTLS
1.1. IP whitelisting
Numeral can whitelist a list or range of IPs and authenticate your API requests against these IPs. To register your IPs, please contact [email protected]. Note that IP whitelisting is not available in sandbox.
1.2. mTLS
If you do not have static IPs or prefer to use mTLS over IP whitelisting, please follow the steps below to generate and share a certificate signing request (CSR) with Numeral.
1.2.1. Generate an authentication certificate private key
Generate an authentication private certificate key using the following bash command.
openssl genrsa -out mtls.key 4096
Make sure to keep this
mtls.key
private key secret. No one but you should get access to it. Additionally, please use a different mTLS certificate for each environment (sandbox and production).
1.2.2. Create a configuration file
Create a configuration file named csr.conf
using the following template.
[req]
default_bits = 4096
distinguished_name = dn
prompt = no
req_extensions = req_ext
[dn]
# Required - Fill in your country code using iso-3166-alpha2-code format
C="FR"
# Required - Fill in your company name
O="Company name"
# Optional - Fill in your organization unit name or comment the following line
OU="Organisational unit / department"
# Required - Fill in your email address
emailAddress="[email protected]"
# Required - Please use one of the following values:
# - sandbox environment: "Numeral sandbox mTLS API"
# - production environment: "Numeral production mTLS API"
CN="Numeral sandbox mTLS API"
[req_ext]
subjectAltName = @alt_names
[alt_names]
# Required - Fill in your domain
DNS.0 = <system/hostname>.yourdomain.com`
Please make sure to replace the above variables with your own values. Additionally, please ensure that the following variables are filled as such:
Variable Comment CN
Please choose the value depending on the environment:
- sandbox: "Numeral sandbox mTLS API"
- production: "Numeral production mTLS API"DNS.0
Your real domain is expected, but you may choose a hostname of your choice and convenience, for instance to distinguish the service and / or the environment calling the Numeral API.
1.2.3. Generate a CSR
Generate an authentication certificate CSR, based on the private key and the configuration file previously created using the following command.
openssl req -new -key mtls.key -out mtls.csr -config csr.conf
After you have generated your authentication certificate CSR, send it to [email protected]. Once signed, we will send you your mtls.crt
certificate used to call the API.
1.2.4 Authenticate your API requests with the certificate
Finally, validate your certificate with a request on our API sandbox endpoint using your certificate.
curl -s \
--key mtls.key \
--cert mtls.crt \
-H 'X-API-KEY: YOUR_API_KEY' \
https://mtls.sandbox.numeral.io/v1/connected_accounts
import requests
url = "https://mtls.sandbox.numeral.io/v1/connected_accounts"
cert = ('path/to/mtls.crt', 'path/to/mtls.key')
headers = {
"accept": "application/json",
"x-api-key": "YOUR_API_KEY"
}
response = requests.get(url, headers=headers, cert=cert)
print(response.text)
Do not forget to use the appropriate URL depending on the environment, either sandbox (
mtls.sandbox.numeral.io
) or production (mtls.api.numeral.io
).
If your server receives an HTTP 200
response with the list of connected accounts, it means that the authentication was successful. Otherwise, 2 situations can occur:
- An
HTTP 403
response with{ "message": "Forbidden" }
in the body means that the certificate is invalid - If no certificate is provided at all, the TLS handshake will fail with the following response:
2. API keys
API keys can be created in the Numeral dashboard by specifying a name and permission (read-only
, modify
, or write
) on the Developers > API keys screen.

The API key must be passed into the X-API-Key
HTTP header of every API call:
curl --request GET \
--url 'https://sandbox.numeral.io/v1/connected_accounts' \
--header 'accept: application/json' \
--header 'x-api-key: YOUR_API_KEY'
All API requests must be made over HTTPS. API requests made over plain HTTP will be rejected. So will API requests sent without a valid API key.
Do not share your API key in publicly accessible areas, such as your GitHub repository, in client-side code, or in log management tools.
If your API key gets compromised, you can disable it and create a new one directly from the Numeral dashboard.