Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/9001/copyparty/llms.txt

Use this file to discover all available pages before exploring further.

copyparty supports multiple authentication methods to suit different clients and use cases.

​
Authentication Methods

Authentication is attempted in the following order:
  1. URL Parameter (?pw=)
  2. HTTP Header (PW:)
  3. Basic Auth (Authorization: Basic)
  4. Cookies (cppwd or cppws)
The first non-empty authentication method is used.

​
URL Parameter Authentication

Include password in the URL: 
curl http://server:3923/folder/?pw=yourpassword

​
With Username

If server has --usernames enabled: 
curl http://server:3923/folder/?pw=username:password
​
pw
string
Authentication credentials. Format:
  • password - Password only (default)
  • username:password - If --usernames is enabled

​
Security Notes

  • URL parameters appear in server logs and browser history
  • Can be disabled server-side with --pw-urlp=A
  • Only use over HTTPS or on trusted networks

​
Configuration

Server can rename or disable URL parameter authentication: 
# Disable URL parameter auth
copyparty --pw-urlp=A

# Rename parameter to 'token'
copyparty --pw-urlp=token

​
HTTP Header Authentication

Use the PW header for authentication: 
curl -H "PW: yourpassword" \
  http://server:3923/folder/

​
With Username

curl -H "PW: username:password" \
  http://server:3923/folder/
​
PW
string
Authentication credentials in password or username:password format

​
Custom Header Name

Server can rename or disable the PW header: 
# Disable PW header auth
copyparty --pw-hdr=A

# Rename to 'X-Auth-Token'
copyparty --pw-hdr=x-auth-token
Then use: 
curl -H "X-Auth-Token: password" \
  http://server:3923/folder/

​
Basic Authentication

Standard HTTP Basic Auth: 
curl -u username:password \
  http://server:3923/folder/
Or manually: 
curl -H "Authorization: Basic $(echo -n 'username:password' | base64)" \
  http://server:3923/folder/
​
Authorization
string
Format: Basic base64(username:password)

​
Disable Basic Auth

copyparty --no-bauth
After successful login via web interface, cookies are set:
  • HTTP: cppwd=hashed-password
  • HTTPS: cppws=hashed-password
curl -b "cppwd=abc123def456" \
  http://server:3923/folder/
​
Cookie
string
Format:
  • cppwd=hash for HTTP connections
  • cppws=hash for HTTPS connections
Cookie values are hashed passwords, not plaintext. Obtain them from browser after login.

​
Account Configuration

Define accounts in server config:

​
Command Line

copyparty -a username:password

​
Config File

[accounts]
  alice: hunter2
  bob: correcthorsebatterystaple
  admin: secretpassword123

​
Permissions

Accounts can have different permissions per volume:
PermissionCodeDescription
ReadrBrowse folders, download files
WritewUpload files
MovemMove files from this folder
DeletedDelete files and folders
GetgDownload files only (no browsing)
UpGetGUpload + receive filekeys
HTMLhServe index.html in folders
AdminaSee upload metadata, reload config
Dots.See dotfiles in listings
AllAEquivalent to rwmda.

​
Example: Volume Permissions

[/music]
  /mnt/music
  accs:
    r: alice, bob      # Read-only for alice and bob
    rw: admin          # Read-write for admin
    g: *               # Anyone can download if they have the URL

​
Authentication Examples

​
Upload with Password

curl -X POST \
  -H "PW: mypassword" \
  -F "f=@file.txt" \
  http://server:3923/uploads/

​
Download with Basic Auth

curl -u alice:hunter2 \
  http://server:3923/files/document.pdf -o document.pdf

​
Search with Header Auth

curl -X POST \
  -H "PW: admin:secretpass" \
  -H "Content-Type: application/json" \
  -d '{"q": "test"}' \
  http://server:3923/

​
List Files with URL Auth

curl "http://server:3923/folder/?ls&pw=alice:hunter2"

​
Security Features

​
Failed Login Bans

Default ban policy (configurable with --ban-pw):
  • 9 failed attempts within 1 hour
  • Results in 24 hour ban
# Custom ban policy: 5 failures in 30 min = 12 hour ban
copyparty --ban-pw 5,1800,43200

​
Password Hashing

Passwords can be hashed in config files: 
# Generate hashed password
copyparty --ah-gen hunter2
Output: 
alice: $2b$12$abc123def456...
Use in config: 
[accounts]
  alice: $2b$12$abc123def456...
Hashed passwords use Argon2 or bcrypt. See Password Hashing for details.

​
IP-Based Authentication

Auto-login from specific IP ranges: 
# Allow 192.168.1.0/24 as user 'alice' without password
copyparty --ipa alice@192.168.1.0/24

​
Restrict Users to IP Ranges

Limit user access by IP: 
[accounts]
  alice: hunter2
    ipa: 192.168.1.0/24, 10.0.0.0/8

​
Authentication Headers in Responses

When authentication fails: 
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Basic realm="a"
Client should retry with credentials.

​
Logout

Logout (clear cookies): 
curl "http://server:3923/?pw=x"
​
pw
string
default:"x"
Set to x to logout and clear authentication cookies

​
Multi-Account Groups

Create groups of users: 
[groups]
  admins: alice, bob
  users: charlie, dave

[/data]
  /mnt/data
  accs:
    rw: @admins    # alice and bob have read-write
    r: @users      # charlie and dave have read-only

​
Built-in Groups

  • @acct - All logged-in users
  • * - Everyone (including anonymous)

​
Exclude from Group

[/public]
  /mnt/public
  accs:
    r: *, -@acct   # Only anonymous users (not logged in)

​
Identity Providers

Replace password auth with OAuth/OIDC: 
# GitHub OAuth
copyparty --idp github

# Generic OIDC
copyparty --idp oidc,https://accounts.google.com
See Identity Providers for configuration.

​
Best Practices

  • Use HTTPS for all authentication in production
  • Prefer header or basic auth over URL parameters
  • Use strong passwords or password hashing
  • Configure IP restrictions for sensitive accounts
  • Enable --usernames if multiple users need same password
  • Use groups for easier permission management
  • Don’t share URLs containing ?pw= parameter
  • Don’t log passwords in client applications
  • Implement retry delays for failed authentications
  • Monitor server logs for authentication failures

​
Troubleshooting

​
Authentication Not Working

  1. Check if auth method is enabled:
    • URL param: Not disabled with --pw-urlp=A
    • Header: Not disabled with --pw-hdr=A
    • Basic: Not disabled with --no-bauth
  2. Verify username format:
    • Without --usernames: Use ?pw=password
    • With --usernames: Use ?pw=username:password
  3. Check account permissions:
    • User has appropriate permission (r, w, etc.)
    • Path is within allowed volumes

​
Failed Login Bans

If you’re banned: 
# Wait for ban duration (default 24h)
# Or have admin clear bans (restart server)
Check current ban settings: 
copyparty --help | grep ban-pw

​
Advanced Configuration

​
User-Changeable Passwords

Allow users to change their own passwords: 
copyparty --pwd-wl alice,bob
Users can then change passwords via web interface.

​
Header-Based Authentication

Authenticate via reverse proxy headers: 
copyparty --xh-name=X-User --xh-pw=X-Password
Proxy must set these headers.

​
Reference

  • Authentication is evaluated per-request
  • No sessions (except cookies from web UI)
  • Permissions are per-volume
  • First matching auth method is used
  • Failed auth triggers ban counter

Build docs developers (and LLMs) love

Get started for freeTalk to us