In order to authenticate their requests to the Numeral API, customers must combine two levels of authentication:

1. One of IP whitelisting OR mutual TLS (mTLS) authentication
2. API key

ℹ️

In sandbox, IP whitelisting is not available and mTLS is optional. This means customers can authenticate their requests using an API key as a single level of authentication.

mTLS and IP whitelisting cannot be combined in production.

1. IP whitelisting and mTLS

1.1. IP whitelisting

Numeral can whitelist a range of IPs to authenticate your API requests against. To register your IPs, please contact [email protected].

1.2. mTLS

If you do not have static IPs or prefer to use mTLS over IP whitelisting, 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 genpkey -algorithm RSA -out private_key.pem -pkeyopt rsa_keygen_bits:4096

🚧

Make sure to keep this private_key.pem private key secret. No one but you should access it. Additionally, 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`

🚧

Make sure to replace the above variables with your own values and ensure that the following variables are filled as such:

Variable	Comment
CN	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 private_key.pem -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 private_key.pem \
    --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/private_key.pem')
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

Generate an API key and pass it into the X-API-Key HTTP header of every API request:

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 with a valid API key. API requests made over plain HTTP will be rejected. API requests sent without a valid API key will be rejected too.

🚧

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.