Master Partners

Master Partners are account-level trading partners that can be shared across multiple tenants within your account. This enterprise feature significantly reduces operational overhead by centralizing partner management and certificate maintenance.

Overview

Traditional AS2 implementations require each tenant to maintain separate partner configurations and certificates. Master Partners solve this by allowing you to:

• Configure once, use everywhere: Set up trading partners at the account level
• Centralized certificate management: Single certificate renewal process
• Operational efficiency: Reduce administrative overhead
• Consistent configuration: Ensure uniform partner settings across tenants

Key Benefits

Operational Efficiency

• Single Configuration: Configure McKesson once, use across all tenants
• Certificate Management: Renew certificates once per partner, not per tenant
• Reduced Errors: Consistent configuration eliminates tenant-specific mistakes

Cost Savings

• Certificate Procurement: Purchase one certificate instead of per-tenant certificates
• Administrative Time: Reduce partner management overhead by 80%+
• Compliance: Centralized audit trails and compliance management

Enterprise Features

• Account Isolation: Master partners are completely isolated per account
• Inheritance Control: Tenants can override master partner settings when needed
• Usage Tracking: Monitor which tenants use each master partner

Master Partner Management

Create Master Partner

POST /v1/accounts/{account}/partners
Content-Type: application/json
Authorization: Bearer pk_live_your_account_key

{
  "name": "McKesson Corporation",
  "as2_id": "MCKESSON",
  "url": "https://as2.mckesson.com/receive",
  "mdn_mode": "async",
  "sign": true,
  "encrypt": true,
  "compress": false,
  "sign_algorithm": "SHA256withRSA",
  "encrypt_algorithm": "AES256_CBC"
}

Response (201):

{
  "message": "Master partner created successfully",
  "data": {
    "id": 123,
    "name": "McKesson Corporation",
    "as2_id": "MCKESSON",
    "url": "https://as2.mckesson.com/receive",
    "active": true,
    "health_status": "excellent",
    "health_score": 100,
    "usage_count": 0,
    "configuration": {
      "mdn_mode": "async",
      "sign": true,
      "encrypt": true,
      "compress": false,
      "sign_algorithm": "SHA256withRSA",
      "encrypt_algorithm": "AES256_CBC"
    },
    "created_at": "2024-01-15T10:30:00Z"
  }
}

List Master Partners

GET /v1/accounts/{account}/partners
Authorization: Bearer pk_live_your_account_key

Query Parameters:

Response (200):

{
  "data": [
    {
      "id": 123,
      "name": "McKesson Corporation",
      "as2_id": "MCKESSON",
      "active": true,
      "health_status": "excellent",
      "health_score": 95,
      "usage_count": 3,
      "configuration": {
        "mdn_mode": "async",
        "sign": true,
        "encrypt": true
      },
      "created_at": "2024-01-15T10:30:00Z"
    }
  ],
  "meta": {
    "total": 5,
    "account_limits": {
      "current_count": 5,
      "limit": 50,
      "can_add_more": true
    }
  }
}

Partner Inheritance

Inherit Master Partner to Tenant

POST /v1/accounts/{account}/partners/{partner_id}/inherit
Authorization: Bearer pk_live_your_account_key

{
  "tenant_id": 456,
  "override_settings": {
    "url": "https://custom-endpoint.tenant.com/as2"
  }
}

Response (201):

{
  "message": "Partner inherited successfully",
  "data": {
    "id": 789,
    "tenant_id": 456,
    "master_partner_id": 123,
    "effective_config": {
      "name": "McKesson Corporation",
      "as2_id": "MCKESSON",
      "url": "https://custom-endpoint.tenant.com/as2",
      "sign": true,
      "encrypt": true
    },
    "override_settings": {
      "url": "https://custom-endpoint.tenant.com/as2"
    }
  }
}

View Inheritance Status

GET /v1/accounts/{account}/partners/{partner_id}/inheritance
Authorization: Bearer pk_live_your_account_key

Response (200):

{
  "data": {
    "master_partner": {
      "id": 123,
      "name": "McKesson Corporation",
      "as2_id": "MCKESSON"
    },
    "total_tenants": 5,
    "inherited_by_count": 3,
    "available_for_count": 2,
    "inherited_by": [
      {
        "partner_id": 789,
        "tenant": {
          "id": 456,
          "name": "East Coast Division",
          "slug": "east-coast"
        },
        "has_overrides": true,
        "override_settings": {
          "url": "https://custom-endpoint.tenant.com/as2"
        },
        "created_at": "2024-01-15T11:00:00Z"
      }
    ],
    "available_for": [
      {
        "id": 457,
        "name": "West Coast Division",
        "slug": "west-coast",
        "status": "active"
      }
    ]
  }
}

Remove Inheritance

DELETE /v1/accounts/{account}/partners/{partner_id}/inherit
Authorization: Bearer pk_live_your_account_key

{
  "tenant_id": 456
}

Master Certificates

Master certificates can be shared across tenants, eliminating the need for per-tenant certificate management.

Certificate Types and Inheritance

Identity Certificates (Account-Level)

• Sender certificates: Used for signing outbound messages from ALL tenants
• Automatic inheritance: All tenants in the account automatically use the account master certificate
• Override capability: Individual tenants can upload their own sender certificate to override the account default
• One certificate for all: Single renewal process instead of per-tenant

Partner Certificates (Via Master Partners)

• Partner public certificates are associated with master partners
• Automatically inherited when tenants use master partners
• Used for encrypting messages to that specific trading partner

Upload Master Certificate

POST /v1/accounts/{account}/certificates
Authorization: Bearer pk_live_your_account_key

{
  "partner_id": 123,
  "type": "sender",
  "common_name": "as2.mycompany.com",
  "certificate_data": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----",
  "kms_key_ref": "arn:aws:kms:us-east-1:123456789012:key/12345678-1234-1234-1234-123456789012"
}

List Master Certificates

GET /v1/accounts/{account}/certificates
Authorization: Bearer pk_live_your_account_key

Query Parameters:

Health Monitoring

Master partners include built-in health monitoring to track connection reliability:

Get Health Statistics

GET /v1/accounts/{account}/partners-health
Authorization: Bearer pk_live_your_account_key

Response (200):

{
  "data": {
    "total_partners": 10,
    "health_distribution": {
      "excellent": 7,
      "good": 2,
      "fair": 1,
      "poor": 0
    },
    "average_health_score": 89.5,
    "overall_health": "excellent"
  }
}

Health Status Levels

Configuration Override

Tenants can override specific master partner settings when needed:

Common Override Scenarios

Custom Endpoint URL

{
  "override_settings": {
    "url": "https://tenant-specific.endpoint.com/as2"
  }
}

Different Security Settings

{
  "override_settings": {
    "encrypt": false,
    "sign_algorithm": "SHA1withRSA"
  }
}

Custom Headers

{
  "override_settings": {
    "headers": {
      "X-Custom-Header": "tenant-specific-value"
    }
  }
}

Best Practices

Master Partner Setup

1. Start with Common Partners: Begin with partners used by multiple tenants
2. Standard Configuration: Use the most common settings as defaults
3. Document Overrides: Keep track of tenant-specific customizations
4. Monitor Health: Regular health checks ensure reliable messaging

Certificate Management

1. Centralize Identity Certificates: Upload ONE sender certificate at account level - all tenants inherit automatically
2. Override When Needed: Specific tenants can upload their own certificate to override the account default
3. Partner Certificate Sharing: Master partner certificates are automatically shared across all tenants using that partner
4. Renewal Planning: Renew account-level certificates once instead of per-tenant
5. Access Control: Use role-based permissions for certificate management

Certificate Resolution Priority for Outbound Messages:

1. Tenant-specific sender certificate (if uploaded)
2. Account-level master sender certificate (inherited automatically)
3. Error if neither exists

Inheritance Strategy

1. Gradual Rollout: Start with a few tenants, expand gradually
2. Test Configurations: Verify settings work before bulk inheritance
3. Override Documentation: Document why overrides are needed
4. Regular Reviews: Periodically review and consolidate overrides

Account Management

Account Structure

Account (Billing Entity)
├── Master Partners (Shared Resources)
│   ├── Master Certificates
│   └── Health Monitoring
├── Tenants (Operational Units)
│   ├── Inherited Partners
│   ├── Tenant-Specific Partners
│   └── Override Settings
└── Users (Access Control)
    ├── Owners (Full Access)
    ├── Billing Admins (Billing Only)
    ├── Admins (Resource Management)
    └── Members (Basic Access)

Role-Based Access

Certificate Usage Example

Scenario: Multi-Tenant Account with 50 Tenants

Traditional Approach (Without Master Certificates):

• Upload 50 sender certificates (one per tenant)
• Renew 50 certificates annually
• Manage 50 separate KMS keys
• High operational overhead

Master Certificate Approach (Recommended):

# Step 1: Upload ONE account-level sender certificate
POST /v1/accounts/acc_123/certificates
{
  "type": "sender",
  "common_name": "as2.mycompany.com",
  "certificate_data": "-----BEGIN CERTIFICATE-----...",
  "private_key_reference": "kms_encrypted_key_reference"
}

# Step 2: ALL 50 tenants automatically inherit this certificate
# No additional configuration needed!

# Step 3: (Optional) Override for specific tenant if needed
POST /v1/tenants/tnt_456/certificates
{
  "type": "sender",
  "common_name": "as2.special-tenant.com",
  "certificate_data": "-----BEGIN CERTIFICATE-----...",
  "private_key_reference": "kms_encrypted_key_reference"
}

Result:

• ✅ 49 tenants use the account master certificate
• ✅ 1 tenant uses its own certificate (override)
• ✅ One certificate renewal process instead of 50
• ✅ 98% reduction in certificate management overhead

Migration from Tenant-Based

If you're migrating from tenant-based partner management:

1. Identify Common Partners: List partners used by multiple tenants
2. Create Master Partners: Convert common partners to master partners
3. Upload Account-Level Certificates: Upload ONE sender certificate at account level
4. Inherit to Tenants: Set up inheritance for existing tenants
5. Test Configurations: Verify all messaging continues to work
6. Clean Up: Remove duplicate tenant-specific partners and certificates

The migration maintains full backward compatibility while providing the operational benefits of master partner sharing.