SFTP Overview

​

Connecting

sftp your-email@yourbank.com@sftp.solo.one

sftp your-email+sandbox@yourbank.com@sftp.solo.one

import paramiko

transport = paramiko.Transport(("sftp.solo.one", 22))
transport.connect(
    username="alice@yourbank.com",
    password="sk_live_your_workos_api_key",
)
sftp = paramiko.SFTPClient.from_transport(transport)

sftp.put("policies.xlsx", "/kyc_cert_policy/policies.xlsx")

sftp.close()
transport.close()

​

How authentication works

1. The username is parsed into an email and an environment tag (+sandbox → sandbox; no tag → production). Usernames are case-insensitive. An unrecognized tag is rejected outright.
2. The password is validated as a WorkOS API key against WorkOS. Revoked or malformed keys are rejected.
3. The key’s owning WorkOS organization — not anything in the username — is resolved to your SOLO organization. Your session is scoped to that organization’s isolated storage area in the selected environment.

​

Directory layout

{category}/{filename}.xlsx

kyc_cert_policy/kyc-policies-2026.xlsx
kyb_cert_policy/kyb-policies.xlsx
programs/network-programs.xlsx
kyc_furnish_data/consumer-batch-jan.xlsx
kyb_furnish_data/business-batch-jan.xlsx

​

What happens on upload

1. Upload. The file lands in your organization’s isolated storage area, prefixed by environment and organization.
2. Trigger. The storage event fires the ingestion workflow for the file’s category — within seconds of the upload completing.
3. Parse. The workbook is read: first sheet only, row 1 treated as a banner, row 2 as headers, row 3+ as data (format details).
4. Ingest. Each row runs through the same furnishing pipeline as the API channels. For data categories that means program routing and furnishing-policy resolution by program_name + application_date; for configuration categories (policies, programs) it means creating governor-controlled network configuration.
5. Record. The outcome — total rows, successes, filtered rows, failures with per-row messages — is recorded as a furnish event you can review in the dashboard.

• Row-level processing — each row succeeds or fails independently. A single invalid row never sinks the rest of the file.
• Filtered is not failed — data rows whose application_date falls outside every applicable policy window are skipped deliberately and reported as filtered.
• Header normalization — headers are lowercased and non-alphanumeric runs collapse to underscores, so column order and cosmetic formatting don’t matter.
• Example-row skipping — rows whose identifier column starts with Ex. are treated as in-workbook examples and skipped.
• Safe re-runs — data rows upsert on their natural keys (SSN for consumers; tax identifier and jurisdiction for businesses), so re-uploading a corrected batch updates records instead of duplicating them. Re-uploaded policy and program rows that collide with existing names surface as per-row name-conflict errors rather than duplicates.

​

File requirements

• Format: Excel workbook (.xlsx)
• Sheet: only the first sheet is read
• Row 1: banner row (ignored)
• Row 2: column headers
• Row 3+: data rows

​

Relationship to the API channels

• The five directories map one-to-one onto the slug values accepted by the bulk file upload endpoint (POST /v1/file-upload/ingest).
• Data rows go through the same program routing and policy resolution as a per-record POST /v1/products/kyc_certificate/furnish call — and earn the same entitlement for your organization.
• The dashboard shows SFTP drops and API uploads in the same uploads view, with the same row-level result reporting.

​

Environments

​

Who can upload what

• Data categories (kyc_furnish_data, kyb_furnish_data) are for organizations holding the furnisher role in the target network.
• Configuration categories (kyc_cert_policy, kyb_cert_policy, programs) define network rules and are enforced as governor-only at ingest — rows uploaded by a non-governor fail with an access error even though the file itself uploads successfully.