SFTP FAQ

General

What is SFTP?

The SSH File Transfer Protocol: file upload and download over an encrypted SSH connection. For this integration it works as a drop box between your systems and Kesk. You upload employee files to it and collect reports from it.

Why SFTP and not an API?

Both exist. SCIM provisioning syncs members from an identity provider, and the GraphQL API can invite and manage members directly. SFTP is for HR and finance systems that can deliver a scheduled file but cannot call an API, so no code has to be written or hosted.

Can we use SCIM and SFTP together?

No. An enterprise runs one or the other. A settings write that would leave both switched on is rejected, so turn one off in the same write that turns the other on. See SCIM or SFTP.

Setting up SFTP

Can we use a password for the SFTP connection?

No. The server rejects every password and accepts SSH public keys only.

Which key types are supported?

Ed25519, RSA, and ECDSA over NIST P-256, P-384 or P-521. Register the public key as a single OpenSSH-format line, such as ssh-ed25519 AAAA....

How do we register a key?

With the addEnterpriseSftpKey operation, called by a signed-in account whose role grants SETTINGS_MANAGE. As of 2026-09-17 that operation is not on the Enterprise API documented here, and the business portal has no screen for it. See setup.

What is our username?

Your enterprise id, which Settings returns as sftpUsername once SFTP is enabled. ent_<id> is accepted too.

What if we have two Kesk enterprises?

Enable SFTP and register a key on each. A key can be registered to only one enterprise, so each needs its own. Each enterprise logs in with its own username and has its own folders.

Can we register more than one key?

Yes. That is how to rotate a key without downtime: add the new key, move your uploads to it, then delete the old one with deleteEnterpriseSftpKey.

Troubleshooting connection issues

How can I test logging in?

With any SFTP client. From a terminal:

Then run ls / and expect to_kesk and from_kesk. To use a graphical client instead (FileZilla, Cyberduck and WinSCP are common), give it the host, port, username and private key from setup.

I am having trouble logging in

Work through these in order:

  1. Network. Your firewall allows outbound connections to sftp.kesk.app on port 2222, not 22.
  2. SFTP is on. sftpEnabled is true in Settings. Switching it off blocks every login, whether or not the key is registered.
  3. The key is registered to this enterprise, and your client is using its private half.
  4. The username is exactly your enterprise id, or ent_ followed by it. A valid key with the wrong username is a failed login.
  5. Lockout. Five failed logins from one IP address block that address until five minutes after the last failure. Wait, then retry once with the right key and username.

"No supported authentication methods" or "Permission denied (publickey)" means one of 2 to 5 above failed. The server does not say which.

Why am I locked out when I only tried once?

Your client probably offered several keys. OpenSSH tries every key in your SSH agent, and each unregistered key counts as a failed login. Five is enough for a lockout. Pass -o IdentitiesOnly=yes with -i so only the right key is offered (backend#908).

The lockout is per IP address, so colleagues behind the same office NAT share it.

I am having trouble deleting a file or creating a folder

You can upload, rename and delete files only under /to_kesk/. Everything under /from_kesk/, including reports, is read-only. Folders are fixed: none can be created, renamed or removed.

My client reports an error after an upload

If the file is on the server, the error is most likely your client setting the file's timestamps or permissions afterwards, which the server does not support. Switch off "preserve timestamps" or its equivalent. Files over 50 MB are refused outright.

The connection keeps closing

The server closes a connection after 60 seconds with no activity. Reconnect for each delivery rather than holding a session open.

My client warns that the host key has changed

Do not accept the new key. Contact [email protected] and confirm the change first. See the host-key note in setup.

Scheduling and syncing

How often should we sync?

As often as your HR changes need. Kesk sets no schedule of its own, and each file is processed when it arrives. Whatever the frequency, give each file time to finish processing before the next one lands in the same folder: its report tells you when it has.

How quickly does Kesk pick up a file?

Processing starts as soon as the upload finishes and runs in the background. There is no published processing-time commitment. The report in /from_kesk/reports/ is written when processing ends, so its arrival is your signal that the file is done.

What safeguards are in place?

  • A full-roster upload to /to_kesk/employees/ is rejected, with nothing applied, if it would remove a large share of your roster. The exact rule is under Safety threshold.
  • Nothing else is guarded. Uploads to remove/ have no threshold, and no one — administrators included — is exempt from removal (backend#906).

Which HR systems can we use?

Any system that can produce a CSV with a header row and deliver it over SFTP with SSH key authentication. See HRIS integration.

Can we sync our roster but keep certain employees out?

Yes: leave them out of the file. With a full-roster upload, the file decides who has access. Anyone already a member who is not in it is removed.

Does a changed name or role in the file update the member?

No. A full-roster upload only invites and removes. People on both the roster and the file are left as they are. Change roles with updateUser.

When is transaction data, such as trips, available?

Not yet. As of 2026-09-17 no exports are generated, and the /from_kesk/trips/, orders/ and invoices/ folders stay empty (backend#904). See Downloading data.

Files and formatting

Does the CSV file name matter?

Only its folder and its extension. The name must end in lowercase .csv, and the folder decides whether the file adds, removes or replaces. Anything else about the name is up to you. Reusing a name overwrites the previous file.

Can the CSV hold a partial list of employees?

Not in /to_kesk/employees/, where the file is treated as the complete roster and anyone missing is removed. For partial lists, upload joiners to /to_kesk/employees/add/ and leavers to /to_kesk/employees/remove/.

Does the file need a header row?

Yes. The first row must name the columns, and one of them must be email. Without it the whole file is skipped, and no report is written (backend#907).

How do I handle commas in a value?

Wrap the value in double quotes: "Lovelace, Ada". To include a double quote inside a quoted value, double it: "Ada ""The Countess"" Lovelace".

What happens if we delete files from/to_kesk/?

Nothing changes on your roster. A file is applied once, when it is uploaded or renamed. Deleting it afterwards does not undo it.

What happens if we upload the same file twice?

It is processed twice. A full roster that already matches changes nothing the second time. An add/ file invites everyone in it again, and they get another email (backend#905).

Reference

Generated reference — every type, field and argument of the Enterprise GraphQL API, built from the live schema. SFTP itself is not GraphQL and is documented in full in this section.

Built with