Skip to content

Use SchemAlign Managed SFTP

SchemAlign Managed SFTP provides organization-scoped file exchange for external systems that need to send files to SchemAlign or retrieve files from it.

Use this guide when the external system connects to SchemAlign's SFTP service. If SchemAlign needs to connect to someone else's SFTP server, use File Get or File Put instead.

Before you begin

You need:

  • permission to administer SFTP Spaces for the organization
  • a Space for the file exchange
  • an SFTP account for the external system or user
  • the external party's SSH public key
  • the SFTP hostname shown for your SchemAlign environment

Managed SFTP uses TCP port 22 unless your environment explicitly provides a different port.

1. Create an SFTP Space

Open Storage → SFTP Spaces and create a Space for the integration.

Each Space receives the standard directories:

<space-alias>/
├── in/
└── out/

Use in/ for inbound files and out/ for files the external party should retrieve.

Processed folders are workflow-specific

SchemAlign does not automatically create in/processed. Create additional folders only when your process needs them.

2. Create the managed SFTP account

Create an SFTP account for the external person or system.

The runtime login name is generated within an immutable tenant namespace. Use the login shown by SchemAlign when configuring the external client.

Managed SFTP accounts use SSH public-key authentication only.

Ask the external party for the public key, for example an OpenSSH-formatted key beginning with:

ssh-ed25519 ...

or another supported SSH public-key type.

Upload or register the public key only. The matching private key remains with the external party.

Never send SchemAlign the private key

Managed SFTP authentication does not require SchemAlign to possess the client's private key.

3. Grant Space access

Grant the account access to the required Space.

Current grant modes are:

Mode Use case
Read only External party retrieves files but cannot change them.
Read & modify External party uploads, overwrites, renames, or deletes files in the Space.

An account sees only explicitly granted Spaces.

Cross-organization grants are not allowed.

4. Connect from an SFTP client

Use the connection details displayed for your SchemAlign environment:

Protocol: SFTP
Host:     <your SchemAlign SFTP host>
Port:     22
Username: <generated managed SFTP login>
Auth:     SSH private key matching the registered public key

Example command-line pattern:

sftp -i /path/to/private_key <username>@<your-schemalign-sftp-host>

After login, the account lands in:

/spaces

and sees only granted Space aliases.

Example:

/spaces/hr-imports/in
/spaces/hr-imports/out

5. Upload an inbound file

Upload inbound files directly into the Space's in/ directory.

Example customer-visible path:

/spaces/hr-imports/in/employees.csv

The canonical path SchemAlign uses internally is:

/hr-imports/in/employees.csv

Both paths reference the same file.

6. Start a pipeline with File Arrival

To automate processing, create a File Arrival trigger for the Space.

File Arrival watches only direct files in in/.

/in/file.csv            -> eligible
/out/file.csv           -> ignored
/in/archive/file.csv    -> ignored
/in/subfolder/file.csv  -> ignored
delete                  -> ignored

Once the file becomes stable, SchemAlign records the arrival and queues a pipeline run in durable FIFO order.

Inside that run, use:

{{trigger.file.sftp_path}}

to reference the exact canonical file path.

A common pattern is:

File Arrival
    ↓
File Get
Remote path = {{trigger.file.sftp_path}}
    ↓
Compose / Destination nodes

File Arrival is detection-only. It does not automatically move, archive, delete, or import the file.

7. Publish outbound files

Place files intended for external retrieval in the Space's out/ directory.

A granted account can retrieve them from:

/spaces/<space-alias>/out/

Creating files in out/ does not trigger File Arrival.

Security model

Managed SFTP is isolated from normal SchemAlign application access.

The service uses:

  • OpenSSH internal-sftp
  • SSH public-key-only authentication
  • SFTP-only sessions
  • no shell or command execution
  • no TCP, agent, or X11 forwarding
  • no TTY
  • organization-scoped identities and Space grants
  • filesystem-enforced jail/bind isolation
  • deny-by-default Space visibility
  • operational auditing for authentication, sessions, file activity, and administrative changes

The SFTP identity cannot use its session to access SchemAlign Workspace, System Logs, application secrets, the host filesystem, or the Docker socket.

Troubleshooting

Authentication fails

Check that:

  • the username exactly matches the generated managed SFTP login
  • the client uses the private key matching the registered public key
  • the managed SFTP account is enabled
  • the public key has not been revoked

A Space is missing after login

The account sees only explicitly granted Spaces. Confirm that the account and Space belong to the same organization and that the grant is active.

Upload or delete is denied

Confirm the grant is Read & modify rather than Read only.

File Arrival did not start a pipeline

Confirm that:

  • the trigger is enabled
  • the file was uploaded directly to in/
  • the file is not in a nested folder
  • the event was a create or overwrite, not a delete
  • the file finished uploading and became stable