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

Level	Description
Network	Network-level authentication mechanisms supported are: * IP whitelisting * Mutual TLS (mTLS) authentication * VPN connectivity * AWS PrivateLink
Application	API keys are used for application-level authentication.

Only mTLS is supported (but optional) in sandbox. # 1. IP whitelisting and mTLS ## 1.1. IP whitelisting Mambu Payments can whitelist a range of IPs to authenticate your API requests against. To register your IPs, please contact [support@numeral.io](mailto:support@numeral.io). ## 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 Mambu Payments. ### 1.2.1. Generate an authentication certificate private key Generate an authentication private certificate key using the following bash command. ```shell 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. ```toml [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@yourdomain.com" # 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 = .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 Mambu Payments 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. ```shell openssl req -new -key private_key.pem -out mtls.csr -config csr.conf ``` After you have generated your authentication certificate CSR, send it to [support@numeral.io](mailto:support@numeral.io). 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 curl -s \ --key private_key.pem \ --cert mtls.crt \ -H 'X-API-KEY: YOUR_API_KEY' \ https://mtls.sandbox.numeral.io/v1/connected_accounts ``` 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: ### 1.2.5. Certificate renewal Mambu Payments supports rolling updates, with old and new certificates accepted during a transition period, to prevent any downtime. # 2. API keys Generate an API key and pass it into the `X-API-Key` HTTP header of every API request: ```curl 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 Mambu Payments dashboard.

What's next

What's next