AS2 / EDI trading partners

VaultTerm can exchange EDI documents with trading partners over AS2 (RFC 4130): signed and encrypted payloads over HTTP, acknowledged with an MDN receipt. This page is written for the person integrating from the other side — it describes what our endpoint expects and, more importantly, what our responses will look like in your logs.

AS2 is off by default on every plan and in every deployment. An organization holds it only by explicit arrangement, and a self-hosted install serves the AS2 routes only when the operator turns them on. If you are not already exchanging AS2 with us, none of the below is reachable.

Configuring the relationship

Each side needs three things from the other:

Field	What it is
AS2 id	The identifier carried in the AS2-From / AS2-To headers. Ours is set per organization.
Certificate	The X.509 certificate whose key signs your messages and whose public half we encrypt to.
Inbound URL	Where you POST to us, and where we POST to you.

Per partner we record whether messages are signed, whether they are encrypted, the MIC algorithm (sha-1, sha-256, sha-384, sha-512), and the MDN mode (sync, async or none). A partner id is unique within an organization: two registrations cannot share one AS2 id, because that row is what decides which certificate authenticates you.

Certificates are validated when they are saved. One that is expired or not yet valid is refused at that point rather than at the first message.

What authenticates an inbound message

Our inbound endpoint is public and the URL carries no secret. The only thing that authenticates you is the CMS signature over the payload, checked against the certificate we hold for you — never the AS2-From header, which anyone can send.

A message that does not verify is not stored, not acknowledged with an EDI 997/CONTRL, and does not appear in the organization’s message ledger. You still receive an MDN telling you it was refused.

If your certificate has expired, the failure MDN says so specifically rather than reporting a generic authentication failure — so a rotation deadline you missed does not look like a broken signature.

Success MDNs

Unchanged and conventional. A successful receipt is signed by our identity certificate and carries the Received-Content-MIC we computed over your payload, so you can reconcile it against what you sent. Nothing in this page changes the success path.

Failure MDNs are unsigned and carry no MIC

This is the one behaviour worth reading before it shows up in your logs.

A failure MDN from us is unsigned and contains no Received-Content-MIC. If your AS2 software validates every MDN’s signature, or reconciles a MIC on failure receipts, it will treat our refusal as a malformed response.

Why. Signing a receipt over content the sender chose, before that sender has been authenticated, turns the failure path into a signing oracle: anyone able to provoke a rejection could obtain our signature over material they influenced. The failure MDN is precisely the response we return to callers we could not authenticate — by definition we do not know who is asking — so it is produced without the organization’s private key being used at all.

How this sits against the spec. RFC 4130 section 7.3.1 states that when a signed receipt is requested and there is an error processing the message, “a signed receipt MUST still be returned. The request for a signed receipt SHALL still be honored, though the transaction itself may not be valid.” Our behaviour is a deliberate deviation from that requirement, recorded here rather than left to be discovered. The argument for it is that the rule is written about a known sender whose message failed to process, whereas our refusal path is reached exactly when the sender is unknown; honouring the signature request there would mean signing for an unauthenticated party. The same section makes an unsigned receipt acceptable when the recipient “cannot support” what was requested, and section 7.4.3 makes Received-Content-MIC optional on an unsigned receipt — so the omitted MIC follows from the unsigned receipt rather than being a second deviation.

If your implementation cannot accept an unsigned failure MDN, tell us: this is a compatibility conversation to have deliberately, not a defect on either side.

EDI acknowledgements and duplicates

When an authenticated payload is recognisable X12 or EDIFACT, we generate the technical acknowledgement (997 or CONTRL) for it — unless the payload is itself a functional acknowledgement.

We detect replayed interchanges by control number. A retransmission of an interchange we already processed is recorded as a duplicate and does not generate a second acknowledgement, so a retry after an MDN timeout is safe. Suppression is scoped to the authentication class of the message that caused it: a message that authenticated by signature is the only kind that can suppress another signed message.

Storage and retention

Received payloads are retained for a bounded window (90 days by default; a self-hosted operator can change it) and are subject to a per-organization storage quota. If a message would take the organization past its quota, it is refused with a failure MDN naming a storage error rather than accepted and silently discarded — the ledger entry recording that your message arrived is kept either way. If you see that disposition, the fix is on our side, not yours; tell us.

The message ledger itself — who sent what, when, the MIC, the disposition, and whether the signature verified — is never removed by retention.

Related

• Security model — how VaultTerm handles keys and encrypted material.
• Integrations — outbound delivery of security events to your own tooling.