Partner Reference

Partner Reference

A partner definition is a reusable YAML file that describes a remote endpoint: its protocol, connection details, authentication, and trust material.

Partners are referenced by flows. Separating partner definitions from flow definitions means you can update connection or trust settings in one place without editing every flow that uses them.

This page is a field-by-field reference. For conceptual context, see Configuration and Protocols.

Who this page is for

• implementers creating partner definitions
• operators reviewing and validating partner configuration
• security reviewers auditing trust and credential handling

File structure

Each partner is a separate YAML file in the directory configured by partners_dir. The filename must match the partner id field exactly (without the .yaml extension).

id: supplier-sftp
display_name: Supplier SFTP
protocol: sftp
sftp:
  host: sftp.supplier.example
  # ...

The loader validates this constraint and rejects files where the filename and id do not match.

Common top-level fields

Field	Type	Required	Description
id	string	yes	Unique partner identifier. Must match the filename.
display_name	string	no	Human-readable label used in the UI.
protocol	string	yes	One of: sftp, ftps, as2, s3, webdav, azure_blob, local.
policy	object	no	Per-partner policy overrides (see below).

Exactly one protocol-specific section must be present and must match protocol.

Partner policy overrides

The policy block lets you set per-partner constraints that apply to flows using this partner.

policy:
  max_file_size: 104857600
  allowed_extensions:
    - .xml
    - .csv
  timeout: 30s
  retries: 3

Field	Type	Description
max_file_size	int64	Maximum file size in bytes for this partner.
allowed_extensions	list	Allowed file extensions. Overrides global allowlist for this partner.
timeout	duration	Connection timeout for this partner (Go duration string, e.g. 30s).
retries	int	Maximum retry attempts for flows using this partner.

---

Protocol: SFTP

id: supplier-sftp
protocol: sftp
sftp:
  host: sftp.supplier.example
  port: 22
  user: xferity-transfer
  remote_dir: /outgoing/invoices
  password: env:SUPPLIER_SFTP_PASSWORD
  key_path: file:/etc/xferity/keys/supplier_id_rsa
  key_passphrase: env:SUPPLIER_KEY_PASS
  known_hosts: file:/etc/xferity/known_hosts
  host_key_fingerprint: "SHA256:abc123..."
  allow_insecure_host_key: false

Field	Type	Required	Default	Description
host	string	yes	—	SFTP server hostname or IP address.
port	int	no	22	SFTP server port.
user	string	yes	—	SSH login username.
remote_dir	string	no	—	Default remote directory. Flows can override with source.path or target.path.
password	string	no	—	Password or secret reference. Use env:, file:, or vault: references.
key_path	string	no	—	Path or secret reference to the SSH private key for key-based authentication.
key_passphrase	string	no	—	Passphrase or secret reference for the private key.
known_hosts	string	no	—	file: reference to an SSH known_hosts file. Must use file: prefix when set.
host_key_fingerprint	string	no	—	SHA-256 fingerprint for host key pinning. Must start with SHA256:.
allow_insecure_host_key	bool	no	false	Disable SSH host key verification. Rejected by hardened mode.

SFTP validation rules

• sftp.host and sftp.user are required.
• sftp.known_hosts must use the file: prefix when set. Bare paths are rejected.
• sftp.host_key_fingerprint must start with SHA256: when set.
• In hardened mode, sftp.password and sftp.key_passphrase must use env:, file:, or vault: secret references. Plaintext values are rejected.
• allow_insecure_host_key=true is rejected in hardened mode.

---

Protocol: FTPS

id: partner-a
protocol: ftps
ftps:
  connection:
    host: ftps.partner-a.example
    port: 21
    passive: true
  auth:
    username: xferity-user
    password: env:PARTNER_A_FTPS_PASSWORD
  tls:
    mode: explicit
    ca_cert: file:/etc/xferity/certs/partner-a-ca.pem
    client_cert: file:/etc/xferity/certs/our-client.pem
    client_private_key: file:/etc/xferity/certs/our-client-key.pem
    client_key_passphrase: env:FTPS_CLIENT_KEY_PASS
    server_cert_fingerprint: ""
    insecure_skip_verify: false

FTPS connection fields

Field	Type	Required	Default	Description
connection.host	string	yes	—	FTPS server hostname or IP.
connection.port	int	no	21	FTPS server port.
connection.passive	bool	yes	—	Must be true. Only passive mode is supported.

FTPS authentication fields

Field	Type	Required	Description
auth.username	string	yes	FTP login username.
auth.password	string	no	Password or secret reference.

FTPS TLS fields

Field	Type	Default	Description
tls.mode	string	explicit	TLS mode. Must be explicit. Implicit mode is not supported.
tls.ca_cert	string	—	env:, file:, or vault: reference to the CA certificate PEM for server validation.
tls.client_cert	string	—	Reference to the client certificate PEM for mutual TLS.
tls.client_private_key	string	—	Reference to the client private key PEM.
tls.client_key_passphrase	string	—	Reference to the client key passphrase.
tls.server_cert_fingerprint	string	—	SHA-256 server certificate fingerprint for pinning.
tls.insecure_skip_verify	bool	false	Skip TLS certificate verification. Rejected by hardened mode.

FTPS validation rules

• connection.host and auth.username are required.
• connection.passive must be true.
• tls.mode must be explicit.
• tls.ca_cert must use a secret reference when set.
• In hardened mode, tls.client_cert, tls.client_private_key, tls.client_key_passphrase, and auth.password must use secret references.
• tls.insecure_skip_verify=true is rejected in hardened mode.

---

Protocol: AS2

id: acme-edi
protocol: as2
as2:
  as2_id: "ACME-CORP-EDI"
  url: "https://edi.acmecorp.example/as2/receive"
  mdn_url: ""
  receipt_mode: sync
  signing_algorithm: sha256
  encryption_algorithm: aes256
  compression_enabled: false
  expect_signed_mdn: true
  https_tls:
    ca_cert: file:/etc/xferity/certs/acme-ca.pem
    client_cert: ""
    client_private_key: ""
    client_key_passphrase: ""
    insecure_skip_verify: false

Field	Type	Required	Default	Description
as2_id	string	yes	—	The partner’s AS2 ID for message routing and MDN correlation.
url	string	yes	—	The HTTP/HTTPS endpoint where AS2 messages are sent.
mdn_url	string	no	—	Async MDN return URL. Required for async MDN. Leave empty for sync MDN.
receipt_mode	string	no	sync	sync or async. Sync MDN is the default.
signing_algorithm	string	no	sha256	Signing algorithm: sha256, sha384, sha512.
encryption_algorithm	string	no	aes256	Encryption algorithm: aes128, aes192, aes256, 3des.
compression_enabled	bool	no	false	Compress the message payload before encryption.
expect_signed_mdn	bool	no	false	Require the MDN receipt to be signed by the partner.

AS2 HTTPS TLS fields

Field	Type	Description
https_tls.ca_cert	string	Reference to a CA certificate PEM for HTTPS trust validation.
https_tls.client_cert	string	Reference to a client certificate for mutual TLS.
https_tls.client_private_key	string	Reference to the client private key.
https_tls.client_key_passphrase	string	Reference to the client key passphrase.
https_tls.insecure_skip_verify	bool	Skip HTTPS TLS verification. Rejected by hardened mode.

AS2 validation rules

• as2_id and url are required.
• receipt_mode must be sync or async.
• In hardened mode, all https_tls credential fields must use secret references.
• https_tls.insecure_skip_verify=true is rejected in hardened mode.

AS2 certificate roles

AS2 partners use certificate bindings for signing, encryption, and verification. These are managed through the Certificate inventory (not in the partner YAML). See Security and the Certificate management UI.

---

Protocol: S3-compatible storage

id: aws-payroll-bucket
protocol: s3
s3:
  bucket: payroll-transfers-prod
  region: eu-west-1
  prefix: inbound/
  endpoint_url: ""
  use_default_chain: true
  access_key_id: ""
  secret_access_key: ""
  session_token: ""

Field	Type	Required	Description
bucket	string	yes	S3 bucket name.
region	string	no	AWS region, e.g. eu-west-1. Required for AWS S3. Optional for S3-compatible APIs.
prefix	string	no	Object key prefix within the bucket. Trailing slash is stripped.
endpoint_url	string	no	Custom endpoint URL for S3-compatible APIs (e.g. MinIO, LocalStack).
use_default_chain	bool	no	Use the AWS SDK default credential chain (IAM roles, env vars, instance metadata).
access_key_id	string	no	AWS access key ID or secret reference. Required when use_default_chain=false.
secret_access_key	string	no	AWS secret access key or secret reference. Required when use_default_chain=false.
session_token	string	no	AWS session token or secret reference for temporary credentials.

S3 validation rules

• bucket is required.
• When use_default_chain=false, both access_key_id and secret_access_key are required.
• In hardened mode, access_key_id, secret_access_key, and session_token must use secret references.

---

Protocol: WebDAV

id: nextcloud-partner
protocol: webdav
webdav:
  url: https://cloud.partner.example/remote.php/dav/files/mftuser
  username: mftuser
  password: env:NEXTCLOUD_PASSWORD
  timeout_seconds: 60
  insecure_skip_verify: false

Field	Type	Required	Default	Description
url	string	yes	—	Base URL of the WebDAV collection. No trailing slash.
username	string	no	—	Basic-auth username. If omitted, no auth header is sent.
password	string	no	—	Password or secret reference.
insecure_skip_verify	bool	no	false	Skip TLS certificate verification. Rejected in hardened mode.
timeout_seconds	int	no	30	Per-request HTTP timeout in seconds.

WebDAV validation rules

• webdav.url is required.
• In hardened mode, webdav.password must use a secret reference when set.
• webdav.insecure_skip_verify=true is rejected in hardened mode.

---

Protocol: Azure Blob Storage

id: azure-reports
protocol: azure_blob
azure_blob:
  account_name: companystorageacct
  container: mft-outbound
  prefix: reports/
  use_default_chain: true

Field	Type	Required	Description
account_name	string	see auth notes	Storage account name. Required for shared-key and default-chain auth.
account_key	string	see auth notes	Storage account key or secret reference. Required when use_default_chain=false and no connection_string.
connection_string	string	see auth notes	Full connection string or secret reference. Alternative to account_name + account_key.
container	string	yes	Blob container name. Must already exist.
prefix	string	no	Blob key prefix within the container.
endpoint_url	string	no	Custom blob service endpoint such as Azurite or Azure Stack.
use_default_chain	bool	no	Use DefaultAzureCredential for managed identity or workload identity scenarios.

Azure Blob validation rules

• azure_blob.container is required.
• Authentication precedence is connection_string → account_name + account_key → use_default_chain.
• In hardened mode, azure_blob.account_key and azure_blob.connection_string must use secret references when set.

---

Protocol: Local filesystem

id: local-landing
protocol: local
local:
  base_path: /mnt/shared/landing

Field	Type	Required	Description
local.base_path	string	yes	Absolute base path for local file operations.

Secret reference syntax

All credential fields in partner definitions support secret references. Use these instead of plaintext values wherever possible.

Prefix	Example	Description
env:	env:PARTNER_SFTP_PASSWORD	Read from an environment variable. Always bootstrap-safe.
file:	file:/run/secrets/partner_password	Read from a file path. Always bootstrap-safe.
vault:	vault:secret/data/mft/partner#password	Read from HashiCorp Vault KV v2.
aws-sm:	aws-sm:prod/mft/partner#password	Read from AWS Secrets Manager.
azure-kv:	azure-kv:partner-sftp-password	Read from Azure Key Vault.
local-vault:	local-vault:partner-sftp-password	Read from local encrypted vault (Postgres backend only).

In hardened mode, credential fields must use secret references. Plaintext values in sensitive fields are rejected at startup.

---

Partner Crypto Policy

In Postgres-backed deployments, each partner has a Partner Crypto Policy view in the UI and API. This shows:

• configured and bound certificate roles (for AS2 and FTPS partners)
• PGP key bindings (for partners using OpenPGP flows)
• health and validation status per role

This view is read-only. Crypto bindings are managed through the Certificate and PGP Key inventory.

---

Complete SFTP partner example

id: bank-sftp
display_name: Bank SFTP (Statement Pickup)
protocol: sftp
sftp:
  host: sftp.bank.example
  port: 22
  user: xferity-transfer
  remote_dir: /outgoing/statements
  known_hosts: file:/etc/xferity/known_hosts
  host_key_fingerprint: "SHA256:abcdefABCDEF0123456789..."
  key_path: file:/etc/xferity/keys/bank_id_rsa
  key_passphrase: env:BANK_KEY_PASS
policy:
  timeout: 60s
  retries: 3

Complete AS2 partner example

id: retail-edi
display_name: Retail Trading Partner EDI (AS2)
protocol: as2
as2:
  as2_id: "RETAIL-PARTNER-EDI"
  url: "https://edi.retailpartner.example/as2/receive"
  receipt_mode: sync
  signing_algorithm: sha256
  encryption_algorithm: aes256
  expect_signed_mdn: true
  https_tls:
    ca_cert: file:/etc/xferity/certs/retail-partner-ca.pem

Related pages

• Flow Reference
• Configuration
• Protocols: SFTP
• Protocols: FTPS
• Protocols: AS2
• Protocols: S3-Compatible Storage
• Security
• Secrets Management