REST API Integration | Aayu Technologies Link Search Menu Expand Document

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 are asc and desc. Defaults to desc.
  • 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 messages
  • stationAS2Id - 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

AttributeDescriptionSample Value
receiverAS2IdReceiver AS2 ID“XYZCorp”
senderAS2IdSender AS2 ID“ACP_PROD”
subjectSubject“AS2 message from ACME Products (MFT Gateway)”
as2MessageIdAS2 message ID562957462970614@mftgateway.com
timestampTimestamp (in ms)1634132550192
attachmentPathsArray of message file paths[AS2/files/XYZCorp /ACP_PROD/inbox/ 562957501929102/aap-sample-po-003.txt”]
micMessage Integrity Check“d24djK1o00pzCp4rlu+3+c8q8q0=, sha1”
incomingdirection, true for incomingtrue
compressedTrue if compressedfalse
signedTrue if signedtrue
encryptedTrue if encryptedfalse
micMatchesTrue if MIC matchesfalse
transportHeadersHTTP headers as key: value pairsAS2-Version: 1.1, Host: mftgateway.com
mdnMessageMDN informationSee below

Additional Information about the Message

AttributeDescriptionSample Value
msgStatusStatus text for message“Received”
mdnStatusStatus text for MDN“Sent Signed MDN”
msgExecutionStatusInternal execution status1
mdnFailureReasonReason text for MDN failure, if any””
transportStatusReceivedHTTP transport status, if any0
userAgentHTTP user agent“Amazon CloudFront”
failureReasonFailure reason text, if any””
apiFetchedFetched by the API flagtrue
idInternal message ID562957501929102
tenantIdInternal tenant ID246669049427362
failuresFailure count, if any0

MDN Information about a Message

AttributeDescriptionSample Value
mdnIdMDN unique ID562957544896774@mftgateway.com
as2MessageIdAS2 message ID562957462970614@mftgateway.com
dispositionDisposition of the MDN“automatic-action/MDN-sent-automatically; processed”
micMessage Integrity Check (MIC)“d24djK1o00pzCp4rlu+3+c8q8q0=, sha1”
signedIs the MDN signed?true
incomingIs this MDN received?false
timestampTimestamp (in ms)1634132555101
messageIdInternal message ID562957501929102
rawMdnS3KeyS3 key for the MDN“AS2/raw-mdn/outgoing/562957501929102/mdn.raw”
humanMessageHuman readable MDNMDN 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
statusMDN 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

AttributeDescriptionSample Value 
nameStation nameACME Backup Station 
as2IdentifierAS2 IdentifierACME_BACK 
emailComma separated list of Email addressesadmin@acme.com 
certificateSee belowtype can be NEW_SELF_SIGN_CERTIFICATE | FROM_KEYSTORE | FROM_CERTIFICATE_STORE 

optional Attributes

AttributeDescriptionSample Value
descriptionDescription for the StationBackup AS2 Station for testing
receivedMessageNotificationsEnable email notifications for received messagesfalse (default)
failedMessageNotificationsEnable email notifications for message send failurestrue (default)
inboundStaticIPEnable static IP for inbound messagesfalse (default)
largePayloadSupportEnable receipt of messages larger than 3MBfalse (default)

Use of Static IP and support for large payload receipt, are based on the subscription tier for the account

Station Certificate

TypeAttributeDescription
NEW_SELF_SIGN_CERTIFICATE  
 passwordPrivate key password. Required
 keyLengthDefault 2048. Allowed 1024, 2048 and 4096
 validityValidity in years. Default 5. Allowed 1,2,5,8,10
 commonNameCertificate Common Name (CN)
 orgUnitOrganizational Unit (OU). Optional
 orgNameOrganization (O). Optional
 cityCity (L). Optional
 stateState (ST). ISO 3166-1 2-character code.Optional
 countryCountry (C). ISO 3166-1 2-character code. Optional
FROM_KEYSTORE  
 keystoreS3 key for existing keystore in the S3 bucket. Required
 keystorePasswordPassword for the keystore. Required
 aliasAlias for the entry in the keystore. Required
 privateKeyPasswordExisting key password for the entry specified by ‘alias’ in the specified ‘keystore’. Required
 newPrivateKeyPasswordNew private key password to save entry with. If not provided, the existing private key password will be used. Optional
FROM_CERTIFICATE_STORE  
 aliasExisting 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

AttributeDescriptionSample Value
nameName assigned to partnerWalmart
as2IdentifierPartner AS2 ID08925485US00
urlTrading Partner URLhttp://gem.wal-mart.com:5080/
encryptionCertificateBase64 encoded encryption certificate

Optional Attributes

AttributeDescriptionValues / Default
encryptMessageEncrypt outbound messages?Default: true
encryptionAlgorithmEncryption algorithmAllowed 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
signMessageSign outbound messages?Default: true
signatureAlgorithmSignature algorithmAllowed algorithms: ‘SHA1’, ‘MD2’, ‘MD5’, ‘SHA224’, ‘SHA256’, ‘SHA384’, ‘SHA512’
Default: ‘SHA1
requestMDNRequest Message Disposition NotificationDefault: true
requestSignedMDNRequest signed Message Disposition NotificationDefault: true
requestAsyncMDNRequest asynchronous Disposition NotificationDefault: false
useDiffCertAsSignCertUse 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
signatureCertificateBase64 encoded signature certificateRequired if useDiffCertAsSignCert is true
httpsCertificateBase64 encoded SSL certificatebase64 certificate for endpoint, especially if not signed by a trusted CA
encryptSignChainCertificatesBase64 encoded encryption/sign chain certificate(s)Array of base64 encoded strings
httpsChainCertificatesBase64 encoded SSL chain certificate(s)Array of base64 encoded strings
validateTrustAnchorValidate trust anchor of the uploaded certificatesDefault: false
compressBeforeCompress messages before encryption/signDefault: false
compressAfterCompress messages after encryption/signDefault: false
useStaticIPUse Static IP for outbound messagesDefault: false
transmissionTimeoutConnection timeoutAllowed values: 60, 120, 180, 300. Default: 120)
descriptionDescription of the trading partner 
messageSubjectDefault message subject for trading partnerMin Length: 1, Max Length: 128
deleteAttachmentsOnSuccessMdnDelete Attachments from the S3 bucket when a successful MDN is receivedDefault: false
autoRetryIncompleteMessagesAuto 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
customHeadersCustom 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

TypeDescription
IDENTITYCertificates used in AS2 Stations
TRUSTCertificates used in AS2 Partners
TRUST_CHAINTrust chain certificates
HTTPSHTTPS Trusted Certificates (For SSL)
HTTPS_CHAINHTTPS 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 KeyNew JSON Object Key
as2MessageIdsmessageIdentifiers

Request query parameter changes:

Old ParameterNew Parameter
as2MessageIdidentifier
stationAS2IdstationIdentifier
partnerAS2IdpartnerIdentifier
-service

Path variables changes:

Old VariableNew Variable
as2_message_ididentifier

Response changes:

Old FieldNew Field
api_tokenapiToken
refresh_tokenrefreshToken
as2messageIdmessageIdentifier
as2MessageIdidentifier
senderAS2IdsenderIdentifier
receiverAS2IdreceiverIdentifier
serialNumber, serial_numberserialNumberHex, serialNumberDecimal
subject_common_namesubjectCommonName
subject_distinguish_namesubjectDistinguishName
issuer_common_nameissuerCommonName
issuer_distinguish_nameissuerDistinguishName
valid_fromvalidFrom
-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.