Underlying provider: Kadence's SFTP-based Directory Sync is powered by WorkOS.

If you can't set up Directory Sync with your identity provider (Okta, Entra, Google, etc.) right away, SFTP lets you onboard some or all of your users into Kadence in the meantime. You upload a CSV of your users to a secure SFTP server, and Kadence syncs from that file.

Some customers use SFTP as their ongoing sync method (for example, by automating a daily upload), while others use it to get started quickly before switching to an identity provider. See Switching to Your Official Provider Later if you'd like to make that move.

Prerequisites

Before you start, make sure you have:

Global Admin access in Kadence
An SSH key pair tool available (ED25519, RSA, or ECDSA; public key must be under 2048 bytes)
An SFTP client: FileZilla, Cyberduck, or WinSCP (Windows)
Your HR system or directory export as a CSV file
Terminal (macOS) or PowerShell / PuTTYgen (Windows)

Enter the Directory Wizard

Once you're ready, follow the steps below to enter the directory sync setup wizard:

Log in to Kadence
Navigate to Settings → Integrations
Scroll to Directory Sync
Click Add Directory Sync
Click Continue
Select SFTP from the bottom of the identity provider list

Step 1: Generate an SSH Key Pair

A key pair is two files:

File	What it is	Where it goes
yourfilename.pub	Public key	Pasted into Kadence (Step 2)
yourfilename (no extension)	Private key	Stays on your machine; used by your SFTP client

Never share or upload your private key.

macOS

Create a folder for the keys first. ssh-keygen won't create a folder that doesn't already exist. Open Terminal (Spotlight: ⌘ + Space, type "Terminal"):

Then run:
```
mkdir -p ~/Documents/SFTP-SSHKeys
```
Alternative: create the folder in Finder, right-click it, then Services → New Terminal at Folder — Terminal opens already pointed at that folder.
Generate the key pair, giving a full path and a filename:
```
ssh-keygen -t ed25519 -f ~/Documents/SFTP-SSHKeys/kadence-sftp
```
1. Press Enter twice to skip the passphrase (recommended — a passphrase has to be re-entered by every tool that uses the key)
2. A passphrase is fine if your security policy requires one — just store it in your password manager

Lock down the private key:

chmod 600 ~/Documents/SFTP-SSHKeys/kadence-sftp

Don't end the -f path with a slash. -f ~/Documents/SFTP-SSHKeys/ fails, because ssh-keygen needs a filename, not just a folder.

Windows — Option A: Built-in OpenSSH (Recommended)

Windows 10 and 11 ship with OpenSSH.

Open PowerShell and run:

mkdir "$HOME\Documents\SFTP-SSHKeys"
ssh-keygen -t ed25519 -f "$HOME\Documents\SFTP-SSHKeys\kadence-sftp"

Press Enter twice to skip the passphrase. You'll get kadence-sftp (private) and kadence-sftp.pub (public) in Documents\SFTP-SSHKeys.

Windows — Option B: PuTTYgen (GUI, required for WinSCP .ppk)

Follows Microsoft's documented process for SFTP key generation:

Download and run PuTTYgen from the PuTTY download page
Under Key, select SSH-2 RSA key
Under Parameters, select RSA
Set Number of bits in a generated key to at least 2048 (4096 preferred)
Click Generate, then move the mouse randomly over the blank area until the progress bar completes
Copy the entire contents of the "Public key for pasting into OpenSSH authorized_keys file" box — including the leading ssh-rsa
Paste it into Notepad and save as kadence-sftp.pub in Documents\SFTP-SSHKeys
Click Save private key and save kadence-sftp.ppk in the same folder
Leave the passphrase blank unless your policy requires one

WinSCP uses the .ppk private key directly. FileZilla will offer to convert a .ppk to its own format the first time you use it.

Reference: Microsoft — Generate an SSH key for SFTP

Where Your Keys Are Saved (the #1 Support Issue)

This is the most common thing that trips people up in this whole setup. If you're missing your key files, check here before contacting support.

What you run	Where the files land	Findable in Finder/Explorer?
ssh-keygen with no -f	~/.ssh/ (macOS) or C:\Users\<you>\.ssh\	❌ Hidden folder
ssh-keygen -f "sftp-key"	Whatever folder the terminal session is in — usually your home folder	⚠️ Easy to lose
ssh-keygen -f ~/Documents/SFTP-SSHKeys/kadence-sftp	Documents/SFTP-SSHKeys/	✅ Yes

If you already generated keys and can't find them:

macOS Finder: press ⌘ + Shift + . to toggle hidden files, or ⌘ + Shift + G and enter ~/.ssh
Windows Explorer: paste %USERPROFILE%\.ssh into the address bar
From the command line: ls -la ~/.ssh (macOS) or dir "$HOME\.ssh" (PowerShell)

Step 2: Upload the Public Key to Kadence

Open the .pub file. In Finder, right-click kadence-sftp.pub → Open With → TextEdit. (On Windows, right-click → Open with → Notepad.) Or print it in Terminal: cat ~/Documents/SFTP-SSHKeys/kadence-sftp.pub
Copy the whole key, starting at ssh-ed25519 (or ssh-rsa) through the end of the base64 string:
Paste it into the Kadence wizard and click Continue. Expected format: <key-type> <base64 body> <optional comment>, separated by single spaces.

Checks before you continue:

✅ Starts with ssh-ed25519, ssh-rsa, or ecdsa-…
✅ Pasted as a single line with no line breaks
✅ Came from the .pub file, not the private key
❌ Don't paste anything beginning with -----BEGIN OPENSSH PRIVATE KEY-----

Step 3: Connect to the SFTP Server

Kadence generates a unique SFTP username once the public key is saved.

Setting	Value
Protocol	SFTP — SSH File Transfer Protocol
Host	sftp.workos.com
Port	Leave blank (defaults to 22)
Logon Type	Key file
User	The username shown in the wizard (copy it from the screen)
Key file	Your private key (kadence-sftp, no .pub)

FileZilla Walkthrough

Open the Site Manager: File → Site Manager (⌘ + S).
Click New site, then fill in the settings above. For Key file, browse to the private key — the file without the .pub extension.
Click Connect. A successful connection shows Directory listing of "/" successful in the log and an empty remote root directory.

If FileZilla says the key file isn't in a supported format, accept its offer to convert it — the converted copy is saved alongside the original.

Step 4: Create and Upload the CSV Files

Your file is treated as your complete active user list. Each time it syncs, Kadence compares it against the previous version — any user missing from the latest upload is removed from Kadence, even if they were included before. If you automate this upload, make sure every current user is included every time; don't send partial or delta files.

File	Required	Purpose
users.csv	✅ Yes	All user records
user_groups.csv	Optional	User-to-group membership
groups.csv	Optional	Group metadata

Upload all files to the root (/) of the SFTP server. Drag them from the left (local) pane to the right (remote) pane in FileZilla.

users.csv Format

Required columns: user_id, first_name, last_name, email.

Kadence-specific optional columns: kadence_teams_1 through kadence_teams_5 and profile_photo_url. These map through Attribute Mapping in your Directory Sync configuration — see our guides on Custom Attribute Mapping for Teams and Custom Attribute Mapping for Profile Photos.

Sample header and row:

user_id,username,email,first_name,last_name,department_name,job_title,kadence_teams_1,kadence_teams_2,kadence_teams_3,kadence_teams_4,kadence_teams_5,profile_photo_url
example@company,example@company,example@company,Example,User,Transmission,62102427|Programme Services Manager,VIP,,,,,

Formatting rules:

Keep the header row exactly as written — column names are case-sensitive
user_id must be unique and stable — if it changes, the sync treats the record as a new user
Leave optional columns empty rather than deleting the column
Save as UTF-8 CSV — watch for Excel adding a BOM or switching to semicolon delimiters in non-US locales
Wrap any value containing a comma in double quotes

user_groups.csv and groups.csv

user_groups.csv needs group_name and user_id — one row per membership
groups.csv needs group_name, and every value must match a group_name used in user_groups.csv

Step 5: Test the Directory Connection

Return to the wizard and run Test Directory Connection.

If files are missing, you'll see this screen — the required users.csv wasn't found at the SFTP root:

Re-check that the file is named exactly users.csv (lowercase) and sits at /, not inside a subfolder.

On success, the wizard confirms "Your directory is successfully connected to Kadence" and offers View Directory. The Directory Sync Configuration page then shows:

Directory provider: SFTP
Directory State: Active
Users count / Groups count
Attribute mapping — kadence_teams_1–kadence_teams_5 and profile_photo_url mapped from your file
Users & Groups tabs listing synced records
Danger zone — Delete directory (removes synced users from Kadence; does not affect your SFTP server)

Sync cadence: WorkOS syncs your SFTP directory whenever it detects a file change, and again every 30 minutes after the initial sync.

Troubleshooting

Symptom	Likely cause	Fix
"No such file or directory" from ssh-keygen	Target folder doesn't exist, or the -f path ends in /	`mkdir -p` the folder; include a filename in -f
Can't find the generated keys	Saved to hidden ~/.ssh/ or to the terminal's working folder	⌘ + Shift + . in Finder, or `ls -la ~/.ssh`
Kadence rejects the public key	Private key pasted, line breaks added, or key over 2048 bytes	Re-copy from the .pub file as one line; use ED25519
SFTP login fails	Wrong username, or public key not yet saved in Kadence	Re-copy the username from Step 3; confirm Step 2 was completed
"Unsupported key file format" in FileZilla	PuTTY .ppk key	Accept FileZilla's conversion prompt
"Please upload all required files"	users.csv missing, misnamed, or in a subfolder	Upload to / with the exact lowercase filename
Users sync but teams are blank	kadence_teams_* columns missing or unmapped	Add the columns; check Attribute Mapping
Duplicate users appear	user_id values changed between exports	Use a stable, immutable ID from your HR system
Users disappear from Kadence unexpectedly	Missing from the latest CSV upload — the file is treated as a full active list, not a delta	Always include every current user in each upload; don't send partial files

Switching to Your Official Provider Later

SFTP works well as an ongoing sync method — many customers automate a daily upload and keep it as their long-term setup. If you'd rather connect an identity provider instead, you can switch at any time.

When you're ready to connect Okta, Entra, Google, or another supported identity provider, follow our Directory Sync Setup Guide. You don't need to remove the SFTP connection first — setting up a new provider will take over directory management for matched users.

Frequently Asked Questions

How often does the SFTP upload sync with Kadence?

WorkOS syncs whenever it detects a change to your uploaded files, and again every 30 minutes as a backstop.

I generated an SSH key but can't find the files. What do I do?

See Where Your Keys Are Saved above — this is the most common step people get stuck on. Short version: if you didn't specify a -f path, your keys are in the hidden ~/.ssh folder.

Do I need to include kadence_teams and profile_photo_url in my CSV?

No — these are optional. user_id, first_name, last_name, and email are the only required columns in users.csv.

What happens if a user is missing from my CSV?

Your file is treated as a full active user list, not a set of incremental changes. If a user who was previously included is missing from a later upload, they'll be removed from Kadence. Always upload your complete, current user list — not just new or changed users.

Can I switch from the SFTP upload to an identity provider like Okta, Entra, or Google later?

Yes. See Switching to Your Official Provider Later above.

What happens to manually invited users once I set up SFTP sync?

If an email match is found between an existing manual user and a user in your CSV, that user is transitioned to being managed by the directory sync. Manual users without a matching row in your CSV stay unmanaged and can continue to be managed manually.

Need Help?

For support, reach out to:
📩 [email protected]

For more helpful articles see:
📚 Kadence Help Center

SFTP Directory Sync Setup Guide