AS2
AS2aaS

API Overview

The AS2aaS API provides programmatic access to all platform functionality through RESTful HTTP endpoints. This document covers API fundamentals, authentication, and core concepts.

Base Configuration

Endpoints

ServiceBase URLPurpose
REST APIhttps://api.as2aas.comAll API operations
AS2 Receivinghttps://as2.as2aas.comInbound AS2 messages

Transport Requirements

RequirementSpecification
ProtocolHTTPS only
TLS Version1.2 minimum, 1.3 recommended
Port443
Content Typeapplication/json
Character EncodingUTF-8

Authentication

API Key Authentication

All API requests require Bearer token authentication.

Required Headers

HeaderTypeRequiredFormatDescription
AuthorizationstringYesBearer {api_key}API key authentication
Content-TypestringYesapplication/jsonRequest content type
AcceptstringYesapplication/jsonResponse content type

Optional Headers

HeaderTypeFormatDescription
X-Tenant-IDstringtnt_000001Switch tenant context
Idempotency-KeystringUUID v4Prevent duplicate operations
User-AgentstringApplication identifierClient identification

API Key Types

Key TypePrefixEnvironmentBilling ImpactUsage
Testpk_test_SandboxNoneDevelopment and testing
Livepk_live_ProductionBillableProduction messaging

Data Types

Primitive Types

TypeFormatConstraintsExample
stringUTF-8 textVariable length"example text"
integerSigned 32-bit-2,147,483,648 to 2,147,483,64742
booleantrue/false-true
datetimeISO 8601UTC timezone"2024-01-15T10:30:00.000000Z"
enumPredefined valuesCase sensitive"active"
arrayJSON array-["item1", "item2"]
objectJSON object-{"key": "value"}

Resource Identifiers

ResourcePrefixFormatPatternExample
Tenanttnt_6 digitstnt_\d{6}tnt_000001
Partnerprt_6 digitsprt_\d{6}prt_000001
Messagemsg_6 digitsmsg_\d{6}msg_000001
Certificatecert_6 digitscert_\d{6}cert_000001
API Keykey_6 digitskey_\d{6}key_000001
Webhookwh_6 digitswh_\d{6}wh_000001

HTTP Methods

Method Usage

MethodPurposeIdempotentCacheable
GETRetrieve resourcesYesYes
POSTCreate resourcesNo*No
PATCHPartial resource updateNo*No
PUTFull resource replacementYesNo
DELETERemove resourcesYesNo

*Idempotent when used with Idempotency-Key header

Rate Limiting

Rate Limits by Plan

PlanRequests/MinuteBurst LimitConcurrent Requests
Free100205
Starter3006010
Professional1,00020025
EnterpriseCustomCustomCustom

Rate Limit Headers

HeaderTypeDescription
X-RateLimit-LimitintegerTotal requests allowed per window
X-RateLimit-RemainingintegerRequests remaining in current window
X-RateLimit-ResetintegerUnix timestamp when limit resets
Retry-AfterintegerSeconds to wait before retrying

Pagination

Pagination Parameters

ParameterTypeDefaultMaximumDescription
pageinteger1-Page number (1-indexed)
per_pageinteger20100Items per page

Pagination Response

FieldTypeDescription
current_pageintegerCurrent page number
last_pageintegerTotal number of pages
per_pageintegerItems per page
totalintegerTotal number of items
fromintegerFirst item number on current page
tointegerLast item number on current page

Error Handling

HTTP Status Codes

StatusNameUsage
200OKSuccessful GET, PATCH, PUT, DELETE
201CreatedSuccessful POST creating new resource
202AcceptedAsynchronous operation accepted
400Bad RequestInvalid request syntax or parameters
401UnauthorizedMissing or invalid authentication
403ForbiddenValid authentication but insufficient permissions
404Not FoundRequested resource does not exist
422Unprocessable EntityRequest validation failed
429Too Many RequestsRate limit exceeded
500Internal Server ErrorServer-side error
503Service UnavailableTemporary service outage

Error Categories

CategoryHTTP StatusDescription
authentication_error401Authentication required or failed
authorization_error403Insufficient permissions
validation_error422Request data validation failed
resource_error404Requested resource not found
rate_limit_error429Rate limit exceeded
transmission_error400AS2 message transmission failed
certificate_error400Certificate validation or processing failed
billing_error402Billing or usage limit issue
server_error500Internal server error

Idempotency

Supported Operations

EndpointMethodIdempotency Support
/v1/messagesPOSTYes
/v1/partnersPOSTYes
/v1/partners/{id}PATCHYes
/v1/certificatesPOSTYes
/v1/webhook-endpointsPOSTYes
/v1/webhook-endpoints/{id}PATCHYes

Idempotency Key Specification

AttributeRequirement
FormatUUID version 4
Header NameIdempotency-Key
Uniqueness ScopePer tenant
Retention Period24 hours
Collision BehaviorReturns original response

Content Encoding

Request Encoding

Content TypeEncodingDescription
application/jsonUTF-8JSON request bodies
multipart/form-dataBinaryFile uploads
application/x-www-form-urlencodedUTF-8Form submissions

Response Encoding

Content TypeEncodingDescription
application/jsonUTF-8JSON response bodies
application/octet-streamBinaryFile downloads
text/plainUTF-8Plain text responses

Request/Response Examples

Successful Request

POST /v1/partners HTTP/1.1
Host: api.as2aas.com
Authorization: Bearer pk_live_abc123def456ghi789jkl012mno345pqr678stu901
Content-Type: application/json
Accept: application/json
Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000

{
  "name": "Acme Corporation",
  "as2_id": "ACME-CORP-AS2",
  "url": "https://acme.example.com/as2",
  "sign": true,
  "encrypt": true
}

HTTP/1.1 201 Created
Content-Type: application/json
X-RateLimit-Limit: 300
X-RateLimit-Remaining: 299
X-RateLimit-Reset: 1705320600

{
  "message": "Partner created successfully",
  "data": {
    "id": "prt_000001",
    "name": "Acme Corporation",
    "as2_id": "ACME-CORP-AS2",
    "url": "https://acme.example.com/as2",
    "active": true,
    "sign": true,
    "encrypt": true,
    "created_at": "2024-01-15T10:30:00.000000Z"
  }
}

Error Response

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json

{
  "message": "Validation failed",
  "errors": {
    "as2_id": [
      "The AS2 ID field is required",
      "The AS2 ID must not contain spaces"
    ],
    "url": [
      "The URL must be a valid HTTPS endpoint"
    ]
  }
}
Messages API