> For the complete documentation index, see [llms.txt](https://docs.payments.thalescloud.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.payments.thalescloud.io/ecom/integrate-the-d1-api/set-up-mutual-tls-mtls.md).
# Set up mutual TLS (mTLS)
The D1 API requires mutual TLS (mTLS). This applies to inbound and outbound API calls.
Set up mTLS before you start integrating D1 eCom Enablement.
You integrate as a merchant gateway. Thales provides you a `merchantGatewayId`.
D1 environments are isolated. Set up connectivity separately for PreProd and Production.
### Inbound flow: your host to Thales D1
mTLS inbound flow
General requirements:
1. Mutual authentication
2. TLS 1.2 or 1.3
3. Over the internet (no IP allowlist)
4. Thales server certificate is signed by AWS CA:
5. Your client certificate is signed by the Thales CA
#### Client certificates
To access the D1 API, you need a client certificate signed by the Thales CA. Send a certificate signing request (CSR) to your Thales representative.
General requirements:
1. Algorithm: RSA encryption with 4096-bit or ECDSA P-256 keys and SHA256 hashing.
2. Common Name (CN): format and value are enforced and checked by Thales. The value should follow the pattern described in step 2 of the example below.
#### Example CSR generation
Repeat the procedure for each environment (PreProd and Production).
1. Generate a new key pair for your CSR either RSA or ECDSA.
You can create a RSA 4096 key pair with the following OpenSSL command:
```bash
openssl req -new -newkey rsa:4096 -nodes -keyout private_rsa.key -out customer_pp.csr -subj "/C=/ST=/L=/O=/OU=/CN=TLSMA-RSA\/\/D1."
```
You can create an ECDSA P-256 key pair with the following OpenSSL commands:
```bash
openssl ecparam -name prime256v1 -genkey -noout -out d1-mtls-client-cert.key
openssl req -new -key d1-mtls-client-cert.key -out d1-mtls-client-cert.csr -subj "/C=/ST=/L=/O=/OU=/CN=TLSMA-ECDSA\/\/D1."
```
2. Details for mTLS client certificate.
where:
* *country* is your country.
* *state* is your state.
* *locality* is your locality.
* *Organization Name* is your organization name.
* *Organizational Unit* is your organizational unit.
* *CN* means Common Name.
* *merchantGatewayId* is the ID provided by Thales.
* *env* is the environment targeted by this certificate. For pre-production: `PPR`, for production: `PRD`
* *ECDSA vs RSA* in CN depends on key type.
{% hint style="info" %}
Your backend must always resolve the D1 domain name and subdomains through DNS. Thales D1 does not provide static IP addresses. Do not hardcode or cache D1 IPs beyond the DNS TTL.
{% endhint %}
### Outbound flow: Thales D1 to your host
mTLS outbound flow
General requirements:
1. Mutual Authentication
2. TLS 1.2, 1.3
3. Your server must listen on port 443 (or 8443, but 443 is preferred)
4. Over the internet (no IP whitelisting)
5. You must trust the Thales Client CA to authenticate the mTLS client certificate presented by D1. The Thales Client CA is shared during onboarding.
6. Thales D1 must trust your server certificate. Provide your server CA chain during onboarding.
{% hint style="info" %}
Thales expects a TLS certificate issued by a CA recognized by Mozilla. If your endpoint relies on a private CA, provide a PEM-formatted trust store to the Thales delivery team. Notify Thales before any CA change.
{% endhint %}
{% hint style="info" %}
You must endorse only the Thales Client CA, and you must not "pin" the Thales client certificate. The Thales client certificate is signed by the Thales Client CA. D1 may rotate its client certificate at any time before its expiry date without prior notice to you.
{% endhint %}
### FAQ
#### Can I use an RSA 2048 client certificate?
No, it is not possible.
#### Can I connect without mTLS?
No, it is not possible.
#### Is VPN supported?
Thales does not support VPN for inbound or outbound connectivity. Use mTLS over the internet. OAuth 2.0 is also required.
#### What is the validity period of the client certificate?
The client certificate issued for Thales backend connectivity is signed by Thales Business PKI and has a validity period of 5 years.
#### What is the renewal process for the client certificate?
During the renewal process, the customer generates a new Certificate Signing Request (CSR) using the Distinguished Name (DN) policy specified on this page. This CSR will then be signed by the Thales Business PKI.
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.payments.thalescloud.io/ecom/integrate-the-d1-api/set-up-mutual-tls-mtls.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.