REST API Integration for AS2
1 Introduction
The MFTGateway exposes a complete REST API for integration. This includes authorization for access, message sending and access, Station and Partner creation, and Certificate details.
Deprecation Notice and Change Summary
In order to be compatible with multiple message services, MFT Gateway has made some changes to the existing message-related API endpoints. Below is a high-level summary of the REST API changes. please click here for more details
1.1 REST API Endpoint
The REST API is available at https://api.mftgateway.com/
. The complete API list and documentation can be found here.
OpenAPI 3.0 specification for the REST API is available here.
1.2 Request Headers
All requests, except the authorization requests, must include an Authorization
header, including a JWT token provided by the Authorization endpoint. The commonly applicable request headers are as follows:
- Authorization - Authorization header with JWT auth token.
- AS2-From - Station AS2 identifier which sends the message.
- AS2-To - Partner AS2 identifier which intends to receive the message.
- Content-Type - Content type of the message payload
- Subject (optional) - Subject of the message. If not specified, the default subject configured for the intended partner will be applied.
- Attachment-Name (optional) - Name of the message attachment.
2 Authorization
For both requests to the following endpoints described in Sections 2.1 and 2.2, a response of the form shown below will be returned, including the JWT auth token, and a refresh token.
{
"api_token": "<JWT_token>",
"refresh_token": "<JWT_token>"
}
2.1 Authorize : POST /authorize
MFT Gateway authorization end-point, to which you are required to send your credentials to obtain an authorization tokens. Make sure to set the Content-Type of the request to ‘application/json’. After being successfully authorized, you will receive two tokens api_token
and a refresh_token
. The api_token
must be included in the Authorization header of every subsequent API request. The refresh_token
can be used for re-authorization process without the user password by using Refresh Auth Token end-point.
Content-Type: application/json
{
"username": "myemail@mydomain.com",
"password": "Abc@1234"
}
2.2 Refresh : POST /refresh-session
This end-point can be used to re-authorize, and receive an updated set of tokens, without providing the user credentials. You can simply send the refresh-token received from initial authentication. Make sure to set the Content-Type of the request to ‘application/json’
Content-Type: application/json
{
"username": "myemail@mydomain.com",
"refreshToken": "refresh_token"
}
3 Message
The message endpoint allows the submission of messages to be sent over AS2, as well as listing the messages in the Received, Sent, Queued, Failed and Incomplete states. Messages may also be retrieved, which also marks them as read. Messages may also be marked as unread, or deleted. Deletion operations allow the deletion of a single message or a batch at once.
3.1 Send (enqueue) AS2 messages : POST /message/submit
Submits an AS2 message, with a single file, or multiple files. Similarly to a submission via the web based console, a message once submitted for sending, is first placed into the Queued state. The response header link
provides an absolute URL for the message. If the actual send operation fails, the message may appear under ‘outbox/failed’ or ‘outbox/error’. The response body also contains the ‘as2MessageId’
Content-Type: application/json
Link: https://api.mftgateway.com/message/outbox/<16037890537199092@mftgateway.com>
{
"message": "Message queued successfully",
"as2MessageId": "<16037890537199092@mftgateway.com>"
}
3.2 List Messages : GET /message/<box>
These API endpoints can be used to list received, sent, failed or incomplete state messages, with optional filters provided as query parameters.
General filters can be applied along with primary or secondary filters.
sortDir
- Sort direction. Possible values areasc
anddesc
. Defaults todesc
.pageOffset
- Page number. An integer value greater or equal to zero is accepted. Default is zero.pageLength
- Length of a page. An integer value greater than or equal to 1 and less than or equal to 100 is accepted. Default is 10.fetchAll
- Fetch all messages, including those already ‘marked as read’. Defaults to false. Applies only to the Inbox
Primary filters have higher precedence over secondary filters. If both primary and secondary filters are found within a request, secondary filters will be ignored.
partnerAS2Id
- AS2 identifier of the AS2 Partner that sent/received these messagesstationAS2Id
- AS2 identifier of the AS2 Station that received/sent these messages
Secondary filters Can be provided only in the absence of any Primary Filters. Only a single secondary filter can be provided per API request, and these are prefix values which will match the start of the AS2 message ID or Subject.
as2MessageId
- ID or ID prefix of the required AS2 message(s)subject
- Subject or Subject prefix of the required AS2 message(s)
For Inbox, list messages API will return messages received and not yet fetched before via a call to this API.
3.3 Retrieve Message
For all message get operations listed under this section, a message of the following form shall be returned.
Key Information about the Message
Attribute | Description | Sample Value |
---|---|---|
receiverAS2Id | Receiver AS2 ID | “XYZCorp” |
senderAS2Id | Sender AS2 ID | “ACP_PROD” |
subject | Subject | “AS2 message from ACME Products (MFT Gateway)” |
as2MessageId | AS2 message ID | “562957462970614@mftgateway.com” |
timestamp | Timestamp (in ms) | 1634132550192 |
attachmentPaths | Array of message file paths | [AS2/files/XYZCorp /ACP_PROD/inbox/ 562957501929102/aap-sample-po-003.txt”] |
mic | Message Integrity Check | “d24djK1o00pzCp4rlu+3+c8q8q0=, sha1” |
incoming | direction, true for incoming | true |
compressed | True if compressed | false |
signed | True if signed | true |
encrypted | True if encrypted | false |
micMatches | True if MIC matches | false |
transportHeaders | HTTP headers as key: value pairs | AS2-Version: 1.1, Host: mftgateway.com |
mdnMessage | MDN information | See below |
Additional Information about the Message
Attribute | Description | Sample Value |
---|---|---|
msgStatus | Status text for message | “Received” |
mdnStatus | Status text for MDN | “Sent Signed MDN” |
msgExecutionStatus | Internal execution status | 1 |
mdnFailureReason | Reason text for MDN failure, if any | ”” |
transportStatusReceived | HTTP transport status, if any | 0 |
userAgent | HTTP user agent | “Amazon CloudFront” |
failureReason | Failure reason text, if any | ”” |
apiFetched | Fetched by the API flag | true |
id | Internal message ID | 562957501929102 |
tenantId | Internal tenant ID | 246669049427362 |
failures | Failure count, if any | 0 |
MDN Information about a Message
Attribute | Description | Sample Value |
---|---|---|
mdnId | MDN unique ID | “562957544896774@mftgateway.com” |
as2MessageId | AS2 message ID | “562957462970614@mftgateway.com” |
disposition | Disposition of the MDN | “automatic-action/MDN-sent-automatically; processed” |
mic | Message Integrity Check (MIC) | “d24djK1o00pzCp4rlu+3+c8q8q0=, sha1” |
signed | Is the MDN signed? | true |
incoming | Is this MDN received? | false |
timestamp | Timestamp (in ms) | 1634132555101 |
messageId | Internal message ID | 562957501929102 |
rawMdnS3Key | S3 key for the MDN | “AS2/raw-mdn/outgoing/562957501929102/mdn.raw” |
humanMessage | Human readable MDN | MDN for Message-ID: 562957462970614@mftgateway.com From: ACP_PROD To: XYZCorp Received on: Wed Oct 13 13:42:34 UTC 2021 Status: processed Comment: This is not a guarantee that the message has been completely processed or understood by the receiving translator. Powered by MFT Gateway |
status | MDN status text | “Sent Signed MDN” |
Sample response
{
"id": 562957501929102,
"as2MessageId": "<562957462970614@mftgateway.com>",
"tenantId": 246669049427362,
"incoming": true,
"msgStatus": "Received",
"mdnStatus": "Sent Signed MDN",
"receiverAS2Id": "XYZCorp",
"senderAS2Id": "ACP_PROD",
"subject": "AS2 message from ACME Products (MFT Gateway)",
"attachmentPaths": [
"AS2/files/XYZCorp/ACP_PROD/inbox/562957501929102/aap-sample-po-003.txt"
],
"timestamp": 1634132550192,
"compressed": false,
"signed": true,
"encrypted": false,
"mic": "d24djK1o00pzCp4rlu+3+c8q8q0=, sha1",
"micMatches": false,
"transportStatusReceived": 0,
"userAgent": "Amazon CloudFront",
"failureReason": "",
"failures": 0,
"mdnFailureReason": "",
"msgExecutionStatus": 1,
"apiFetched": true,
"transportHeaders": {
"AS2-From": "ACP_PROD",
"AS2-To": "XYZCorp",
"AS2-Version": "1.1",
"Disposition-Notification-Options": "signed-receipt-protocol=required,pkcs7-signature;
signed-receipt-micalg=required,sha1",
"Content-Type": "multipart/signed; protocol=\"application/pkcs7-signature\";
micalg=sha1; \tboundary=\"----=_Part_8_1954761469.1634132547185\"",
"Disposition-Notification-To": "someone@somewhere.com",
"Host": "stjsx7kuo9.execute-api.us-east-1.amazonaws.com",
"From": "someone@somewhere.com",
"Subject": "AS2 message from ACME Products (MFT Gateway)",
"Message-Id": "<562957462970614@mftgateway.com>",
"MIME-Version": "1.0",
},
"mdnMessage": {
"mdnId": "<562957544896774@mftgateway.com>",
"messageId": 562957501929102,
"as2MessageId": "<562957462970614@mftgateway.com>",
"disposition": "automatic-action/MDN-sent-automatically; processed",
"humanMessage": "This is not a guarantee that the message has been completely
processed or understood by the receiving translator",
"rawMdnS3Key": "AS2/raw-mdn/outgoing/562957501929102/mdn.raw",
"mic": "d24djK1o00pzCp4rlu+3+c8q8q0=, sha1",
"signed": true,
"incoming": false,
"status": "Sent Signed MDN",
"timestamp": 1634132555101
}
}
3.3.1 Retrieve Inbox (Received) Message : GET /message/inbox/:as2-message-id
Return the Inbox message with the given AS2 message ID. Unless the markAsRead
parameter has been provided as false
, this call will automatically mark the returned message as ‘read by the API’, as the flag defaults to true
. Once a message has been marked as ‘read by the API’, subsequent list queries will not return the message as a result. (You can override this behaviour by specifying the fetchAll
flag as true
in the list queries). Using this default behaviour it is possible to process received messages only once.
Note: Messages marked as ‘read by the API’ will still show-up as new or unread messages in the web console Inbox. The UI level and API level flags are separate.
3.3.2 Mark Received Message As UnRead : POST /message/inbox/:as2_message_id/markUnread
This end-point can be used to mark received AS2 message as ‘unread by the API’. Please note that the result of this operation will not affect the status displayed on the web console Inbox.
3.3.3 Retrieve Outbox (Sent/Queued/Failed/Incomplete) Message : GET /message/outbox[/queued | /failed | /incomplete]/:as2-message-id
This API endpoint can be used to retrieve outbox (sent/queued/failed/incomplete) message by AS2 message identifier.
3.3.4 Retrieve Message Attachments
Appending /attachments
to any Inbox or Outbox request described in Sections 3.3.1 or 3.3.3, will return the individual attachment fetch URLs as follows. The signed URLs are valid for a period of 10 minutes.
e.g.
GET /message/outbox/:as2MessageId/attachments
{
"total": 1,
"attachments": [
{
"name": "EDI_Purchase_Order_0001.raw",
"url": "https://mftg-bucket.s3.amazonaws.com/AS2/files/station/partner/outbox/01234-012/Attachment.raw?
X-Amz-Algorithm=...&X-Amz-Credential=AS...&X-Amz-Date=20200728T110019Z&X-Amz-Expires=600
&X-Amz-Security-Token=...&X-Amz-Signature=...&X-Amz-SignedHeaders=host"
}
]
}
3.3.5 Retrieve Message MDN
Appending /mdn
to any Inbox or Outbox request described in Sections 3.3.1 or 3.3.3, will return the MDN fetch URL as follows. The signed URL is valid for 10 minutes.
e.g.
GET /message/outbox/:as2MessageId/mdn
{
"url": "https://mftg-bucket.s3.amazonaws.com/AS2/raw-mdn/incoming/1234567890/mdn.raw?
X-Amz-Algorithm=...&X-Amz-Credential=AS...&X-Amz-Date=20200728T110019Z&X-Amz-Expires=600
&X-Amz-Security-Token=...&X-Amz-Signature=...&X-Amz-SignedHeaders=host"
}
3.4 Delete Message
Submitting an HTTP DELETE call to the message URLs described in Sections 3.3.1 or 3.3.3 will delete the message from the system. This applies for messages in the Inbox and Outbox, and messages in Queued, Failed and Incomplete states.
DELETE /message/outbox/:as2MessageId
{
"deleted": "<16206212538784367@mftgateway.com>"
}
3.5 Batch Delete : POST /message/<box>/delete
A batch delete request would provide a list of message IDs to be deleted from the system. This API is available for both Inbox and Outbox messages, including those in Queued, Failed or Incomplete state.
e.g.
POST /message/inbox/delete
{
"as2MessageIds": [
"<16206212538784368@mftgateway.com>",
"<16094169443904964@mftgateway.com>"
]
}
Response confirmation
{
"deleted": [
"<16206212538784368@mftgateway.com>",
"<16094169443904964@mftgateway.com>"
]
}
4 Station : POST /station
This API can be used to create a new AS2 Station.
Mandatory Attributes
Attribute | Description | Sample Value | |
---|---|---|---|
name | Station name | ACME Backup Station | |
as2Identifier | AS2 Identifier | ACME_BACK | |
Comma separated list of Email addresses | admin@acme.com | ||
certificate | See below | type can be NEW_SELF_SIGN_CERTIFICATE | FROM_KEYSTORE | FROM_CERTIFICATE_STORE |
optional Attributes
Attribute | Description | Sample Value |
---|---|---|
description | Description for the Station | Backup AS2 Station for testing |
receivedMessageNotifications | Enable email notifications for received messages | false (default) |
failedMessageNotifications | Enable email notifications for message send failures | true (default) |
inboundStaticIP | Enable static IP for inbound messages | false (default) |
largePayloadSupport | Enable receipt of messages larger than 3MB | false (default) |
Use of Static IP and support for large payload receipt, are based on the subscription tier for the account
Station Certificate
Type | Attribute | Description |
---|---|---|
NEW_SELF_SIGN_CERTIFICATE | ||
password | Private key password. Required | |
keyLength | Default 2048. Allowed 1024, 2048 and 4096 | |
validity | Validity in years. Default 5. Allowed 1,2,5,8,10 | |
commonName | Certificate Common Name (CN) | |
orgUnit | Organizational Unit (OU). Optional | |
orgName | Organization (O). Optional | |
city | City (L). Optional | |
state | State (ST). ISO 3166-1 2-character code.Optional | |
country | Country (C). ISO 3166-1 2-character code. Optional | |
FROM_KEYSTORE | ||
keystore | S3 key for existing keystore in the S3 bucket. Required | |
keystorePassword | Password for the keystore. Required | |
alias | Alias for the entry in the keystore. Required | |
privateKeyPassword | Existing key password for the entry specified by ‘alias’ in the specified ‘keystore’. Required | |
newPrivateKeyPassword | New private key password to save entry with. If not provided, the existing private key password will be used. Optional | |
FROM_CERTIFICATE_STORE | ||
alias | Existing IDENTITY type certificate alias, from the certificate store |
e.g.
curl --location --request POST 'https://api.mftgateway.com/station' \
--header 'Authorization: auth-token' \
--data-raw '{
"name": "Station With Self Signed Certificate",
"as2Identifier": "station_with_self_signed_certificate",
"email": "email1@email.com,email2@email.com,email3@email.com",
"certificate": {
"type": "NEW_SELF_SIGN_CERTIFICATE",
"commonName": "Certificate CN",
"password": "private-key-password",
"keyLength": 2048,
"validity": 5,
"orgUnit": "Organization Unit",
"orgName": "Organization Name",
"city": "City",
"state": "State",
"country": "US"
}
}'
Sample response on successful creation
{
"message": "Station created successfully",
"stationId": 555119144483082
}
5 Partner : POST /partner
This API can be used to create a new AS2 Partner.
Mandatory Attributes
Attribute | Description | Sample Value |
---|---|---|
name | Name assigned to partner | Walmart |
as2Identifier | Partner AS2 ID | 08925485US00 |
url | Trading Partner URL | http://gem.wal-mart.com:5080/ |
encryptionCertificate | Base64 encoded encryption certificate |
Optional Attributes
Attribute | Description | Values / Default |
---|---|---|
encryptMessage | Encrypt outbound messages? | Default: true |
encryptionAlgorithm | Encryption algorithm | Allowed algorithms: ‘DES_EDE3_CBC’, ‘AES128_CBC’, ‘AES192_CBC’, ‘AES256_CBC’, ‘CAMELLIA128_CBC’, ‘CAMELLIA192_CBC’, ‘CAMELLIA256_CBC’, ‘CAST5_CBC’, ‘RC2_CBC’, ‘SEED_CBC’, ‘ECDH_SHA1KDF’ Default: ‘DES_EDE3_CBC’ |
signMessage | Sign outbound messages? | Default: true |
signatureAlgorithm | Signature algorithm | Allowed algorithms: ‘SHA1’, ‘MD2’, ‘MD5’, ‘SHA224’, ‘SHA256’, ‘SHA384’, ‘SHA512’ Default: ‘SHA1’ |
requestMDN | Request Message Disposition Notification | Default: true |
requestSignedMDN | Request signed Message Disposition Notification | Default: true |
requestAsyncMDN | Request asynchronous Disposition Notification | Default: false |
useDiffCertAsSignCert | Use a different certificate to verify signature of the inbound messages. If set to false encryptionCertificate will be used to validate incoming message signatures. | Default: false |
signatureCertificate | Base64 encoded signature certificate | Required if useDiffCertAsSignCert is true |
httpsCertificate | Base64 encoded SSL certificate | base64 certificate for endpoint, especially if not signed by a trusted CA |
encryptSignChainCertificates | Base64 encoded encryption/sign chain certificate(s) | Array of base64 encoded strings |
httpsChainCertificates | Base64 encoded SSL chain certificate(s) | Array of base64 encoded strings |
validateTrustAnchor | Validate trust anchor of the uploaded certificates | Default: false |
compressBefore | Compress messages before encryption/sign | Default: false |
compressAfter | Compress messages after encryption/sign | Default: false |
useStaticIP | Use Static IP for outbound messages | Default: false |
transmissionTimeout | Connection timeout | Allowed values: 60, 120, 180, 300. Default: 120) |
description | Description of the trading partner | |
messageSubject | Default message subject for trading partner | Min Length: 1, Max Length: 128 |
deleteAttachmentsOnSuccessMdn | Delete Attachments from the S3 bucket when a successful MDN is received | Default: false |
autoRetryIncompleteMessages | Auto retry incomplete messages. Incomplete messages may have been successfully processed by the trading partner, but failed to respond before the connection timeout. If sets to true there is a possibility for duplicate messages. | Default: false |
customHeaders | Custom transport headers to be included in the outbound messages to this trading partner. | Array of {“headerName”: “string”, “headerValue”: “string”}) Following header names are reserved and cannot be used. ‘as2-from’, ‘as2-to’, ‘as2-version’, ‘content-transfer-encoding’, ‘content-type’, ‘disposition-notification-options’, ‘mime-version’, ‘message-id’, ‘receipt-delivery-option’, ‘destination’ |
e.g.
curl --location --request POST 'https://api.mftgateway.com/partner' \
--header 'Authorization: auth-token' \
--data-raw '{
"name": "Partner Name",
"as2Identifier": "partner_as2_id",
"url": "https://partner.com",
"encryptionCertificate": "<Base64 encoded encryption certificate>",
"encryptMessage": true,
"encryptionAlgorithm": "DES_EDE3_CBC",
"signMessage": true,
"signatureAlgorithm": "SHA1",
"httpsCertificate": "<Base64 encoded SSL certificate>",
"httpsChainCertificates": [
"<Base64 encoded SSL chain certificate one>",
"<Base64 encoded SSL chain certificate two>"
],
"customHeaders": [
{
"headerName": "<custom-header-name>",
"headerValue": "<custom-header-value>"
}
]
}'
Sample response
{
"message": "Partner created successfully",
"partnerId": 555131984980067
}
6 Certificates : GET /certificate[?certType=<type>]
This API endpoint can be used to list the already configured, and available certificates on the account. The results could be optionally filtered by providing a certType
query parameter.
certType - Certificate type to filter
Type | Description |
---|---|
IDENTITY | Certificates used in AS2 Stations |
TRUST | Certificates used in AS2 Partners |
TRUST_CHAIN | Trust chain certificates |
HTTPS | HTTPS Trusted Certificates (For SSL) |
HTTPS_CHAIN | HTTPS chain certificates (For SSL) |
Sample Response
[
{"alias":"5fa241b0-7ea6-42a2-9539-fbeb9125f671","type":"TRUST"},
{"alias":"b3294fa5-4e2b-4a84-8a80-fa800e230171","type":"IDENTITY"},
{"alias":"6cdb1f3b-9fcc-4b4a-8b64-96b80ab81deb","type":"IDENTITY"}
]
6.1 Download certificate : GET /certificate/:alias
Appending /:alias
to the certificate endpoint described in Sections 6, will return the individual certificate details as follows
e.g.
{
"alias": "f54967f4-23fb-4b1a-9759-ba6b94cd7922",
"type": "HTTPS",
"serial_number": "66c9fcf99bf8c0a39e2f0788a43e696365bca",
"subject_common_name": "Amazon Root CA 1",
"subject_distinguish_name": "CN=Amazon Root CA 1, O=Amazon, C=US",
"issuer_common_name": "Amazon Root CA 1",
"issuer_distinguish_name": "CN=Amazon Root CA 1, O=Amazon, C=US",
"valid_from": "Tue May 26 00:00:00 UTC 2015",
"expiry": "Sun Jan 17 00:00:00 UTC 2038",
"belongsTo": [
"Partner-01",
"Station_02"
]
}
7 Deprecation Notice and Change Summary
In order to be compatible with multiple message services, MFT Gateway has made some changes to the existing message-related API endpoints. Below is a high-level summary of the REST API changes.
Request body changes:
Old JSON Object Key | New JSON Object Key |
as2MessageIds | messageIdentifiers |
Request query parameter changes:
Old Parameter | New Parameter |
as2MessageId | identifier |
stationAS2Id | stationIdentifier |
partnerAS2Id | partnerIdentifier |
- | service |
Path variables changes:
Old Variable | New Variable |
as2_message_id | identifier |
Response changes:
Old Field | New Field |
api_token | apiToken |
refresh_token | refreshToken |
as2messageId | messageIdentifier |
as2MessageId | identifier |
senderAS2Id | senderIdentifier |
receiverAS2Id | receiverIdentifier |
serialNumber, serial_number | serialNumberHex, serialNumberDecimal |
subject_common_name | subjectCommonName |
subject_distinguish_name | subjectDistinguishName |
issuer_common_name | issuerCommonName |
issuer_distinguish_name | issuerDistinguishName |
valid_from | validFrom |
- | validFromTimestamp |
- | expiryTimestamp |
MFT Gateway will support both old and new fields/parameters for backward compatibility in current versions, and will remove old ones completely after 01 January 2023.