How to Set Up HTTPS Client Certificate Authentication (mTLS) for Your AS2 Connection

Nov 10, 2026 ·

Overview

You can set up HTTPS client certificate authentication (mutual TLS, or mTLS) on your AS2 connections yourself through the ECGridOS API. When it's on, ECGrid presents a client certificate to your trading partner's HTTPS endpoint during the TLS handshake, and the partner validates it before accepting the connection.

When you need this: your trading partner asks for ECGrid's "client authentication certificate" so they can trust or whitelist it. It's often used in place of HTTP Basic Authentication (user name and password).

This is not your AS2 certificate. Your AS2 signing/encryption certificate secures the message itself. The mTLS client certificate secures the connection. They are separate certificates on the same connection:

Before you start

You'll need:

• An active ECGridOS API session (SessionID) with permission to manage the connection.
• The CommID of the AS2 connection to your trading partner (or the details to create a new one).
• If you'll use your own certificate: the certificate and private key as a .pfx or .p12 file, and its password.

Ask your trading partner these questions first. Their answers decide how you set things up:

1. Will you accept a self-signed certificate, or must it be issued by a public certificate authority (CA)? Self-signed: let ECGridOS generate it (step 2, Option A). CA-issued: upload your own (step 2, Option B).
2. Does the client certificate replace Basic Authentication, or do you need both?
3. What format do you want the public certificate in (PEM or DER), and do you need the full chain?

Steps

1. Turn on client certificate authentication for the connection.
   • New connection: call CommAddA with SSLClientAuthentication = true.
   • Existing connection: call CommUpdateA with your CommID and SSLClientAuthentication = true. Re-send the connection's current values for the other fields so they don't change.
   • If the certificate replaces Basic Authentication, set HTTPAuthentication = None and leave HTTPUser and HTTPPassword empty.
2. Add the client certificate to the same CommID.Choose one option:
   • Option A, ECGridOS generates a self-signed certificate: call CertificateCreatePrivate with Usage = SSL, SecureHashAlgorithm = sha2, a BeginUsage date and an Expires date.
   • Option B, upload your own certificate (for example, CA-issued): call CertAddPrivateA with CertType = X509, Usage = SSL, CertBase64 = your .pfx or .p12 file encoded as Base64, and Password = the file's password.
3. Get the public certificate and send it to your partner.
   • Both calls return the connection's Certificates list. Find the entry where Usage is SSL.
   • Check that HasPrivateKey is true and that Thumbprint, NotBefore and NotAfter are what you expect.
   • Copy its PublicCertificate value (Base64). To make a PEM file, put it between -----BEGIN CERTIFICATE----- and -----END CERTIFICATE----- lines and save it as a .cer or .pem file.
   • Send your partner the public certificate only. Never send the private key or the .pfx file.
4. Test. After your partner confirms they've trusted the certificate, send a test file. A successful delivery and MDN confirm the TLS handshake works.
5. Plan for renewal. Note the NotAfter date. At least 30 days before it, add a new certificate (step 2) and send your partner the new public certificate, so they can trust both during the changeover.

Sample requests

SOAP 1.1 bodies for the ECGridOS v4.1 endpoint https://os.ecgrid.io/v4.1/prod/ECGridOS.asmx. Replace the values in brackets.

Step 1: enable client certificate authentication on an existing connection (SOAPAction: "https://os.ecgrid.io/CommUpdateA")

<CommUpdateA xmlns="https://os.ecgrid.io/">
  <SessionID>[your session ID]</SessionID>
  <CommID>[CommID]</CommID>
  <OwnerUserID>[owner user ID]</OwnerUserID>
  <Identifier>[your AS2 ID]</Identifier>
  <URL>[partner's HTTPS AS2 URL]</URL>
  <Version>[current value]</Version>
  <SignData>true</SignData>
  <EncryptData>true</EncryptData>
  <CompressData>[current value]</CompressData>
  <ReceiptType>[current value]</ReceiptType>
  <HTTPAuthentication>None</HTTPAuthentication>
  <HTTPUser></HTTPUser>
  <HTTPPassword></HTTPPassword>
  <SSLClientAuthentication>true</SSLClientAuthentication>
  <UseType>[current value]</UseType>
  <BeginUsage>[current value]</BeginUsage>
  <EndUsage>[current value]</EndUsage>
</CommUpdateA>

Step 2, Option A: generate a self-signed client certificate (SOAPAction: "https://os.ecgrid.io/CertificateCreatePrivate")

<CertificateCreatePrivate xmlns="https://os.ecgrid.io/">
  <SessionID>[your session ID]</SessionID>
  <CommID>[CommID]</CommID>
  <BeginUsage>2026-12-01T00:00:00Z</BeginUsage>
  <Usage>SSL</Usage>
  <SecureHashAlgorithm>sha2</SecureHashAlgorithm>
  <PartnerAS2ID>[partner's AS2 ID]</PartnerAS2ID>
  <Expires>2028-12-01T00:00:00Z</Expires>
</CertificateCreatePrivate>

Step 2, Option B: upload your own client certificate (SOAPAction: "https://os.ecgrid.io/CertAddPrivateA")

<CertAddPrivateA xmlns="https://os.ecgrid.io/">
  <SessionID>[your session ID]</SessionID>
  <CommID>[CommID]</CommID>
  <CertType>X509</CertType>
  <KeyId></KeyId>
  <UserId></UserId>
  <BeginUsage>2026-12-01T00:00:00Z</BeginUsage>
  <Usage>SSL</Usage>
  <PartnerAS2ID>[partner's AS2 ID]</PartnerAS2ID>
  <CertBase64>[Base64 of your .pfx file]</CertBase64>
  <Password>[.pfx password]</Password>
</CertAddPrivateA>

Full definitions for every operation are in the ECGridOS API v4.1 reference.

Troubleshooting and FAQ

Can I use my AS2 signing certificate for mTLS? Use a separate certificate with Usage = SSL. That way you can renew or replace one without affecting the other.

Do I need Basic Authentication too? Only if your partner asks for both. Most partners use the client certificate in place of Basic Authentication.

Still stuck? Contact support@ecgrid.com with your CommID and the error your partner sees.

Related articles

• How to Set up your AS2 Connection to ECGrid
• ECGRID AS2 Certificate is Expiring
• ECGridOS API v4.1 reference