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.

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: Use account-level sender/receiver certificates
2. Partner Certificate Sharing: Share partner public certificates across tenants
3. Renewal Planning: Set up auto-renewal for critical certificates
4. Access Control: Use role-based permissions for certificate management

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

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. Inherit to Tenants: Set up inheritance for existing tenants
4. Test Configurations: Verify all messaging continues to work
5. Clean Up: Remove duplicate tenant-specific partners

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