Session URL

<protocol> :// [ <username> [ : <password> ] [ ; <advanced> ] @ ] <host> [ : <port> ] /

The only mandatory part is host. The host can either be a host name (such as example.com), an IPv4 address (such as 127.0.0.1) or an IPv6 address surrounded by square brackets (such as [2001:db8:85a3:8d3:1319:8a2e:370:7348]).

You should also always explicitly specify a protocol (sftp, ftp, scp, s3, for FTP over implicit TLS/SSL use ftps, for FTP over explicit TLS/SSL use ftpes, for WebDAV use http, for WebDAV over TLS/SSL use https).1 For all protocols WinSCP-specific alternative is supported, with winscp- prefix.

Most URL’s will include also username.

The port needs to be specified only, when it differs from the default port for the protocol (22 for sftp/scp, 21 for ftp and ftpes, 990 for implicit ftps, 80 for http and 443 for https and s3).

A session URL can optionally set any advanced session settings using a syntax based on raw site settings.

Providing advanced settings in the session URL is mainly useful, if you need to provide all session settings using URL only, such as using a hyperlink on a web page; or when you want to serialize all session settings into a single “connection string”, such as when passing the current setting settings to a WinSCP extension.

A syntax to serialize raw site settings is ;x-name1=value1;x-name2=value2 (inserted after username and password).

For example to use an HTTP proxy server proxy, use the following URL:
sftp://username:password;x-proxymethod=3;x-proxyhost=proxy@example.com/

To have WinSCP generate a session URL with the advanced settings, check Advanced settings on Generate session URL/code dialog. To serialize all session settings for a WinSCP extension, use !E pattern.

This feature is available only in the latest beta release.

There’s a special syntax to include an expected SSH host key fingerprint in SFTP/SCP URL among advanced site settings: fingerprint=<fingerprint>.

For security reasons, fingerprint provided in session URL does not override any fingerprint already cached on the machine. This for instance differs from behavior, when fingerprint is provided using -hostkey switch of open command in scripting.

Format of the fingerprint for URL2 somewhat differs from format used in other WinSCP features (-hostkey switch of open command in scripting for instance). To convert WinSCP fingerprint format to URL format:

1. Drop bit count part (the number after ssh-rsa or ssh-dsa, typically 2048 or 1024);
2. Replace remaining space and all colons (:) with a dash sign (-).

For example WinSCP fingerprint ssh-rsa 2048 ee:f3:c1:59:4d:b4:e2:c5:da:22:3a:6e:97:a0:28:29 converts to ssh-rsa-ee-f3-c1-59-4d-b4-e2-c5-da-22-3a-6e-97-a0-28-29.

Special characters (like @ in username, see example below) have to be encoded using %XX syntax, where XX is hexadecimal UTF-8 code.3

Common special characters are:

• space: %20 or +
• #: %23 (number sign/hash)
• %: %25 (percent sign)
• +: %2B (plus sign)
• /: %2F (slash)
• @: %40 (at sign)
• :: %3A (colon)
• ;: %3B (semicolon)

Note that when specifying session URL on command-line, you cannot use characters that have special meaning on Windows command-line, just as with any other command-line argument. Such characters include & (ampersand), | (pipe), < (less-than sign), > (greater-than sign), " (double-quote). To escape these characters, you can wrap whole session URL to double-quotes (") or encode the characters as shown above.

Further, in Windows batch files, % (percent sign) needs to be doubled to be used correctly, even when the sign is itself used to encode other special characters. For example, to use @ in a username, specify ‘’40''. You can have WinSCP [[ui_generateurl|generate correct URL]] for all kinds of uses (command-line, script or batch file). ===== Examples ===== sftp://martin:mypassword@example.com/ sftp://root@example.com:2222/ ftp://127.0.0.1:2121/ ftp://[2001:db8:85a3:8d3:1319:8a2e:370:7348]:2121/ sftp://martin;fingerprint=ssh-dss-0b-77-8b-68-f4-45-b1-3c-87-ad-5c-be-3b-c5-72-78@example.com/ http://martin@example.com/dav/ ===== Other Uses ===== You can also paste session URL on [[ui_login|Login dialog]] or main window or even Windows Explorer or web browser (if WinSCP is [[integration_url|registered]] to handle file transfer protocol URL addresses). ~dcd41269e53c3bb2a714f76effc6e90c~ ~08104ecdb4b9c6afed97d1b3ac006405~ You can use [[custom_command|custom command]] pattern ''!S'' to pass a session URL%% to other processes.