AS2TroubleshootingHTTPEDI

AS2 HTTP 401 and 403 Errors: Authentication Fixes That Actually Work

8 min readBy Marwan Nakhaleh

Your AS2 server POSTs the message and the partner's endpoint answers with HTTP 401 Unauthorized or HTTP 403 Forbidden. No MDN, no AS2 level error, nothing in the disposition field. The rejection happened at the HTTP layer, before any AS2 software on the other side ever saw your message.

That detail is the key to fixing it. Certificates, signing, encryption, MDN settings: all irrelevant here. Something in front of the partner's AS2 software refused the HTTP request itself. Here are the five causes, how to confirm each, and the fix.

A quick decoder: 401 means "who are you?" and usually wants credentials. 403 means "I know the request, and the answer is no," which points at allowlists, WAFs, and policy. Servers blur the line in practice, so check both sets of causes if the first does not pan out.

Cause 1: The endpoint expects HTTP basic auth and you are not sending it

Some trading partners, and most of the big retail and 3PL gateways that front AS2 with an API gateway, require a username and password on the HTTP request itself, separate from all AS2 level security.

How to confirm: A textbook 401 includes a WWW-Authenticate: Basic realm="..." response header. Reproduce it outside your AS2 stack: curl -v -X POST https://partner.example.com/as2 and read the response headers. If adding -u user:pass with the credentials from the partner's spec sheet turns the 401 into anything else, you found it.

The fix: Add the credentials to the partnership's outbound HTTP settings. mendelson exposes HTTP authentication fields per partner; other stacks want an Authorization: Basic header configured on the send channel. Watch for expiring gateway passwords: a connection that worked for months and now returns 401 often means the partner rotated credentials on schedule and the memo missed you.

Cause 2: Your IP is not on the partner's allowlist

The most common 403. Many partners only accept AS2 traffic from registered source IPs. The classic trigger: you migrated servers, moved to the cloud, or your NAT gateway changed, and your outbound traffic now leaves from an address the partner never registered.

How to confirm: Find your actual egress IP with curl https://ifconfig.me from the AS2 server itself, not your laptop. Compare it against what the partner has registered. A 403 with an empty or generic body, arriving instantly, fits the allowlist pattern. So does a connection that broke the same week as an infrastructure change.

The fix: Send the partner your current egress IP and ask them to confirm registration in writing. Then make that IP static: an elastic IP on a NAT gateway in the cloud, a reserved address on premises. If your platform cannot guarantee a fixed egress IP, fix that first, because this error will keep coming back.

Cause 3: Wrong AS2-From or AS2-To identifiers

Some gateways validate the AS2-From and AS2-To headers before accepting the message body, and return 403 for unknown identifiers instead of the polite AS2 behavior of returning an MDN with authentication-failed.

How to confirm: Pull the exact header values from your outbound log and compare them character by character against the partner's spec. AS2 IDs are case sensitive: ACMECORP and AcmeCorp are different identities. Check for leading or trailing whitespace, and remember an ID containing spaces must be sent inside double quotes per RFC 4130.

The fix: Correct the identifiers to an exact match and resend. When onboarding, paste IDs from the partner's document rather than retyping them. If the 403 persists with verified IDs, ask the partner whether your identity is actually provisioned on their side; a configured but unactivated partnership produces the same symptom.

Cause 4: The partner requires a TLS client certificate

Mutual TLS setups demand that your server present a client certificate during the TLS handshake. Some gateways terminate the handshake when it is missing; others complete the handshake and answer the request with 403.

How to confirm: Check the partner's connectivity spec for mutual TLS or client certificate requirements. Then test: curl -v --cert client.pem --key client.key https://partner.example.com/as2. If the 403 disappears with the certificate attached, that is your cause.

The fix: Install the client certificate on your outbound channel. Note this is a TLS layer certificate, separate from your AS2 signing and encryption certificates, though some partners let you reuse the same key pair. The AS2 certificates guide explains how the layers differ.

Cause 5: The URL path is wrong and you are hitting a different application

The host resolves, TLS works, and your POST lands on the partner's web server, just not on the AS2 receiver. A corporate SSO portal, an IIS default site, or an API gateway answers instead, with a 401 or 403 of its own.

How to confirm: Read the response body, not just the status code. An HTML login page or a branded error page means you never reached AS2 software. Path conventions differ by product: mendelson listens at /as2/HttpReceiver, pyAS2 at /pyas2/as2receive, and commercial gateways define custom paths per partner. A missing or extra path segment is enough.

The fix: Confirm the full URL with the partner, including scheme, port, and the complete path, then set it exactly in your partnership config. In OpenAS2 that is the as2_url attribute on the partnership.

Identify the cause without the email ping pong

Each of these confirmations takes a curl command on your side or a config check on theirs. Chasing them serially through a partner's support queue takes days.

Run them all at once instead. The free AS2 connection test exercises the full HTTP and AS2 round trip against an endpoint and reports the TLS handshake, HTTP response, identifier handling, and MDN behavior as separate graded checks, so a 401 or 403 comes with its likely cause attached. For everything beyond the HTTP layer, work through the complete AS2 connection failed troubleshooting guide, and see how to test an AS2 connection for the full checklist.

60 seconds. 8 checks. One answer.