> 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/dynamic-cvv/integrate-the-d1-api/set-up-tls-mutual-authentication.md).

# Set up TLS mutual authentication

All D1 APIs require **TLS mutual authentication**. This applies to inbound and outbound connectivity.

Set up TLS mutual authentication before you configure any D1 service. Each D1 environment uses a single endpoint for all D1 APIs.

PreProd and Production are isolated from each other. Set up TLS mutual authentication separately for each environment.

TLS mutual authentication is configured per **issuer identifier**. Your Thales Delivery Team provides the issuer identifier during D1 Onboarding.

<figure><img src="/spaces/62lLFDcmLCeqqwmy4Fee/files/JGUTGTF81wFiJ2yWsPRZ" alt=""><figcaption><p>TLS mutual authentication from the issuer backend to the D1 backend.</p></figcaption></figure>

Once TLS mutual authentication is established, you can use it for all D1 APIs. The target paths may differ by D1 service.

#### Requirements

1. Mutual Authentication
2. TLS 1.2, 1.3
3. Over the internet (no IP allowlisting)
4. D1 server CA: signed by AWS CA <https://www.amazontrust.com/repository/>
5. Issuer client certificate: signed by the Thales CA

#### Issuer client certificate

To call the D1 API, your issuer backend must present a client certificate signed by the Thales CA. Send a Certificate Signing Request (CSR) to the Thales Delivery Team for signing.

#### **Requirements**

1. Algorithm: RSA encryption with 4096-bit or ECDSA P-256 keys and SHA256 hashing.
2. Common Name (CN): the format and value are enforced by Thales. Use the pattern in step 2 below.

#### **Example CSR generation**

Repeat this procedure for each environment you target: PreProd and Production.

1. Generate a new key pair for your CSR either RSA or ECDSA.

You can create an RSA 4096 key pair with the following OpenSSL command:

```sh
openssl req -new -newkey rsa:4096 -nodes -keyout private_rsa.key -out issuer_pp.csr -subj "/C=<Country>/ST=<State>/L=<Locality>/O=<Issuer Organization>/OU=<Issuer Organization Unit>/CN=TLSMA-RSA\/<issuerId>\/D1.<env>"
```

You can create an ECDSA P-256 key pair with the following OpenSSL commands:

```sh
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=<country>/ST=<state>/L=<locality>/O=<Issuer Organization>/OU=<Issuer Organization Unit>/CN=TLSMA-ECDSA\/<issuerId>\/D1.<env>"
```

2. Details for mTLS client certificate.

where:

* *country* is the issuer country.
* *state* is the issuer state or region.
* *locality* is the issuer locality (city).
* *Issuer Organization* is your issuer organization name.
* *Issuer Organization Unit* is your issuer organization unit.
* *CN* is the Common Name.
* *issuerId* is the issuer identifier provided by the Thales Delivery Team.
* *env* is the target environment for this certificate. Use `PPR` for PreProd and `PRD` for Production.
* *ECDSA vs RSA* in CN depends on key type.

### DNS requirements

Do not configure, hardcode, or cache D1 IP addresses beyond the DNS TTL.

The issuer backend must always resolve the D1 domain name and its subdomains using DNS. D1 does not provide long-term static IP addresses.

<figure><img src="/spaces/62lLFDcmLCeqqwmy4Fee/files/4vWmDugatLPzgMfLYQiV" alt=""><figcaption><p>TLS mutual authentication from the D1 backend to the issuer backend.</p></figcaption></figure>

### Requirements

1. Mutual Authentication
2. TLS 1.2, 1.3
3. Your server must listen on port 443 (8443 is supported, but 443 is preferred)
4. Over the internet (no IP whitelisting)
5. Trust the Thales Client CA to authenticate the client certificate presented by D1 (shared during D1 Onboarding)
6. Provide your server CA chain during D1 Onboarding so D1 can trust your server certificate

{% hint style="info" %}
Thales expects a TLS certificate issued by a CA recognized by Mozilla. If the endpoint you expose to the D1 backend relies on a private CA, or does not include the full CA chain in its TLS configuration, provide a PEM-formatted trust store to the Thales Delivery Team.

Notify Thales in advance before you change any CA.
{% endhint %}

{% hint style="warning" %}
Trust only the Thales Client CA. Do not pin the Thales client certificate.

D1 may rotate its client certificate at any time before expiry without prior notice.
{% endhint %}

## FAQ

<details>

<summary>Can I use an RSA 2048 client certificate?</summary>

No. D1 requires RSA 4096 or ECDSA P-256.

</details>

<details>

<summary>Can I connect to the D1 backend without TLS mutual authentication?</summary>

No. TLS mutual authentication is required for all D1 APIs.

</details>

<details>

<summary>Is VPN supported for inbound or outbound connectivity?</summary>

No. Use TLS mutual authentication over the public internet for both directions.

For inbound calls, also use OAuth JWT Bearer credentials to authorize access.

</details>

<details>

<summary>Is OAuth supported from the D1 backend to the issuer backend?</summary>

Yes, OAuth is supported in both communication way.

</details>

<details>

<summary>What is the validity period of the issuer client certificate?</summary>

The issuer client certificate for D1 connectivity is signed by Thales Business PKI. It is valid for 5 years.

</details>

<details>

<summary>How do I renew the issuer client certificate?</summary>

Generate a new CSR that follows the Distinguished Name (DN) policy on this page. Send the CSR to the Thales Delivery Team for signing.

</details>


---

# 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/dynamic-cvv/integrate-the-d1-api/set-up-tls-mutual-authentication.md?ask=<question>
```

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.