Manage SFTP feeds & Push API keys

Outcome

Inbound data sources — vendor SFTP drops or real-time push API integrations — registered, credentialed, and bound to a mapping definition so files turn into canonical entities the moment they arrive.

Prerequisites

Scope	What it lets you do
ingestion.feed.read	View feed list, batches, artifacts
ingestion.feed.write	Add / edit feeds; mint API keys; configure SFTP

A mapping definition for the data shape you expect — see 5.5 — Manage ingestion mappings.

SFTP polling vs Push API

	SFTP polling	Push API
Direction	We connect out to the vendor	The vendor connects in to us
Cadence	Cron-scheduled	On every push
Credentials	Vendor's SFTP login	Our minted bearer key
Best for	Daily / hourly batch files	Real-time event streams

A feed is exactly one of the two. You can have many feeds per vendor.

Feed detail tabs

Configuration → Ingestion → Feeds opens the list. Each feed detail page has four tabs:

Tab	What you do here
Overview	Name, format, mapping binding, status.
SFTP (SFTP feeds only)	Host, schedule, credentials, Test Connection, Trigger Poll.
Keys (Push feeds only)	Mint, view, revoke API keys.
Artifacts	The most recent inbound files / batches per cron tick.

Add an SFTP feed

1. Click + New feed on the list page. Choose SFTP for the source type. Fill in:

   • Name — display label.
   • Source format — CSV, X12, FHIR, HL7v2, FIXED_WIDTH.
   • Mapping — the mapping definition that transforms inbound rows.
   • Cron schedule — accepts shorthand (@hourly, @daily, every-15-minutes) or full cron syntax.

2. Open the SFTP tab to set credentials. The form takes host, port, username, remote path, and one of password OR private-key path. The secret never appears in the UI after save; the form clears.

3. Click Test connection. The platform connects to the SFTP host, authenticates, and lists the remote path. Failure returns the raw transport-level error.

4. Optional Trigger poll runs a single immediate fetch outside the cron schedule. Useful for testing or backfill of a known recent file.

Add a Push API feed

1. Click + New feed and choose Push for the source type. Fill in name, source format, and mapping (same as SFTP).

2. Open the Keys tab to mint an API key. The dialog displays the bearer token once — copy it now or you will need to re-mint. The platform stores only a hash.

   The vendor sends POST /api/v1/ingest/push/<feed_id> with header Authorization: Bearer <key> and a JSON or multipart body matching the feed's source format.

3. Up to 5 active keys per feed. Use multiple keys when you want fine-grained revocation: separate dev/prod, separate per-vendor-system. Old keys can be revoked at any time without affecting the others.

4. Watch the usage drawer. Each key tracks request count and average latency at 1h / 24h / 7d windows. Useful for noticing a vendor whose push rate is dropping unexpectedly.

Inspect an artifact

The Artifacts tab on either feed type lists the latest inbound files / batches. Click a row to open the artifact detail page, which shows:

Section	Content
Header	Filename / push id, size, timestamp.
Batch	The processing batch's status (RECEIVED → PARSED → MAPPED → COMPLETED).
Records	Sample of mapped rows.
Errors	Per-row mapping or validation failures.

Validation

Check	Expected
Feed appears on /admin/ingestion/feeds	Yes.
Test connection (SFTP) returns success	Yes.
Pushed file (Push API) creates a batch row	Yes — visible on the Artifacts tab within seconds.
Mapping binding fires on first batch	Yes — batch progresses from RECEIVED to MAPPED.

Troubleshooting

Symptom	Cause	Fix
SFTP poll silently does nothing	Cron expression invalid	The schedule field validates client-side; clear and re-enter.
Push request returns 401	Wrong / revoked key	Mint a new key; update the vendor.
Push request returns 429	Per-feed rate limit hit	Default is generous; if hit, contact your platform admin to raise.
Batch stays at RECEIVED	Mapping not bound	Bind a mapping under the feed's Overview tab.
Batch progresses to FAILED	Mapping transform threw	Open the artifact detail; the failing row + error is logged.

Next

6.1 — Member detail walkthrough