Core Concepts

Understanding these fundamental concepts will help you effectively integrate with AS2aaS and build robust AS2 messaging solutions.

Table of Contents

• AS2 Protocol Overview
• Account-Based Architecture
• Trading Partners
• Messages and Payloads
• X.509 Certificates
• Message Disposition Notifications (MDN)
• API Keys and Authentication
• Webhooks and Events
• Multi-tenant Architecture

AS2 Protocol Overview

What is AS2?

AS2 (Applicability Statement 2) is a specification for the secure and reliable transport of business data over the internet. It's widely used in industries like healthcare, retail, and manufacturing for exchanging EDI documents and other business-critical information.

Key AS2 Features

AS2 Message Flow

Account-Based Architecture

Hierarchical Structure

AS2aaS uses an account-based architecture that provides operational efficiency and centralized management:

Account (Billing Entity)
├── Master Partners (Shared Resources)
│   ├── McKesson Corporation
│   ├── Cardinal Health  
│   └── AmerisourceBergen
├── Master Certificates (Shared Security)
│   ├── Account Identity Certificate
│   └── Master Partner Certificates
├── Tenants (Operational Units)
│   ├── East Coast Division
│   │   ├── Inherited Master Partners
│   │   ├── Tenant-Specific Partners
│   │   └── Configuration Overrides
│   ├── West Coast Division
│   └── Manufacturing Division
└── Users (Access Control)
    ├── Account Owners
    ├── Tenant Administrators
    └── Tenant Members

Key Benefits

Account vs Tenant Operations

Trading Partners

Partner Types

AS2aaS supports two types of trading partners that work together in the account-based architecture:

Master Partners (Account-Level)

Shared trading partners managed at the account level:

• Scope: Available to all tenants in the account
• Management: Created via /v1/accounts/{account}/partners
• Use Case: Common industry partners (McKesson, Cardinal Health, etc.)
• Benefits: Single configuration, shared certificates, reduced operational overhead

Tenant Partners

Tenant-specific trading partners:

• Scope: Limited to individual tenant
• Management: Created via /v1/partners
• Use Case: Tenant-specific suppliers, regional partners, testing partners
• Benefits: Tenant isolation, specialized configurations

Partner Resolution and Inheritance

When tenants access partners, they receive both types:

graph TD
    A[Tenant Request] --> B{Partner Resolution}
    B --> C[Tenant-Specific Partners]
    B --> D[Inherited Master Partners]
    C --> E[Combined Partner List]
    D --> E
    E --> F[Partner with Override Capability]

Partner Configuration Elements

Configuration Override Capability

Tenants can override master partner settings when needed:

Partner Relationship Types

Messages and Payloads

Message Structure

AS2 messages consist of multiple layers:

Message Components

Content Types

Message Lifecycle

X.509 Certificates

Certificate Architecture

AS2aaS implements a hierarchical certificate management system aligned with the account-based architecture:

Master Certificates (Account-Level)

• Scope: Shared across all tenants in the account
• Management: Via /v1/accounts/{account}/certificates
• Benefits: Single certificate renewal, consistent security policies
• Use Case: Account identity certificates, master partner certificates

Tenant Certificates

• Scope: Limited to specific tenant
• Management: Via /v1/certificates
• Benefits: Tenant-specific security requirements
• Use Case: Tenant identity certificates, tenant-specific partner certificates

Certificate Types and Scoping

Certificate Resolution Priority

When processing AS2 messages, certificates are resolved in this order:

1. Tenant-specific certificate (highest priority)
2. Account master certificate (inherited)
3. System default certificate (fallback)

Certificate Usage by Scope

Certificate Inheritance Benefits

Certificate Lifecycle

Message Disposition Notifications (MDN)

MDN Purpose

MDNs provide cryptographic proof that a message was successfully received and processed by the intended recipient. They serve both technical and legal purposes in business communications.

MDN Modes

MDN Content

API Keys and Authentication

Authentication Model

AS2aaS uses API key-based authentication with Bearer token format. API keys can be scoped to either account-level or tenant-level access, supporting the account-based architecture.

Key Types and Scoping

Account-Scoped Keys (pk_live_..., pk_test_...)

• Access: All tenants within the account
• Master Partners: Can manage account-level master partners
• Billing: Account-level usage tracking
• Use Case: Administrative operations, cross-tenant management

Tenant-Scoped Keys (tk_live_..., tk_test_...)

• Access: Single tenant only
• Master Partners: Can view inherited master partners (read-only)
• Billing: Tenant-level usage attribution
• Use Case: Application integrations, tenant-isolated operations

Key Environments

Permission Scopes

Account-Level Scopes

Tenant-Level Scopes

Webhooks and Events

Event-Driven Architecture

AS2aaS uses webhooks to provide real-time notifications about message status changes, partner events, and system events. This eliminates the need for constant API polling.

Event Categories

Webhook Security

Multi-tenant Architecture

Account-Tenant Relationship

AS2aaS implements a hierarchical multi-tenant architecture where tenants exist within accounts:

Account (acme-corp)
├── Tenant: East Coast Division (tnt_east)
├── Tenant: West Coast Division (tnt_west)  
├── Tenant: Manufacturing Division (tnt_mfg)
└── Tenant: European Operations (tnt_eu)

Tenant Concept

A tenant represents an operational unit or business division within an account. Tenants provide operational isolation while benefiting from shared account-level resources.

Resource Sharing and Isolation

Tenant Benefits from Account Architecture

Tenant Context and Switching

Using Account-Scoped Keys

GET /v1/partners HTTP/1.1
Authorization: Bearer pk_live_account_key
X-Tenant-ID: tnt_000002

Using Tenant-Scoped Keys

GET /v1/partners HTTP/1.1
Authorization: Bearer tk_live_tenant_key
# Automatically scoped to tenant

Tenant Management Operations

Data Flow Concepts

Outbound Message Flow

Inbound Message Flow

Security Concepts

Defense in Depth

AS2aaS implements multiple security layers:

Certificate Management

Integration Patterns

Common Integration Approaches

Error Handling Strategies

Performance Considerations

Message Processing Performance

API Performance

Compliance and Auditing

Audit Trail

AS2aaS maintains comprehensive audit logs for compliance requirements:

Compliance Features

Business Use Cases

Healthcare and Pharmaceuticals

Retail and Supply Chain

Manufacturing

Error Handling Concepts

Error Categories

Recovery Strategies

Monitoring and Observability

Key Metrics

Alerting Strategy

Development Best Practices

Environment Management

Testing Strategy

Code Organization

Next Steps

After understanding these core concepts, proceed to:

1. Quick Start Guide - Hands-on tutorial
2. Authentication - API key setup
3. Messages API - Detailed API reference
4. Partners API - Partner management
5. Webhooks - Event notifications