Password Protection & Protected Paths

Protection lives in an AUTH file (no extension) at the root of the directory you publish. Every line is a rule: a path pattern, then who's allowed. Rules ship with your files when you publish—no dashboard, no separate setup, and no login code in your project; the edge handles everything before your files are served.

/admin/*   jane@example.com

AUTH is a paid-plan feature—publishing a project that contains one prompts you to upgrade right in the CLI if you haven't already. See Plans.

Who's allowed

A rule lists one or more principals after the path. There are two kinds:

Principal Who it matches How they get in
jane@example.com Exactly that address The sign-in page
*@example.com Anyone at that domain The sign-in page
collaborators Anyone you've invited to this domain The sign-in page
user:password Whoever knows the password Browser password prompt, or curl -u

Identity principals send visitors to Surge's sign-in page. A rule names email addresses; the page offers three ways to prove one—sign in with Google, with GitHub, or with a Surge account's email and password. The rule doesn't care which: whichever a visitor uses, a verified email that matches lets them in, for 12 hours across the whole domain. The people you name don't need a Surge account—any Google or GitHub account works as-is (GitHub counts every verified address on the account; Surge accounts sign in once their email address is verified, and are asked for their code as part of the same sign-in if they keep two-factor auth on). Credential principals are classic HTTP basic auth.

Rules

Write as many rules as you need, one per line. The first rule that matches the request path decides; blank lines and # comments are ignored.

# who can see what
/admin/*     collaborators
/drafts/*    *@example.com
/internal/*  jane@example.com sam@partner.co

A /* pattern covers the entire domain (a bare * means the same thing):

/*   collaborators

collaborators tracks your collaborator list on its own: invite someone with surge invite and once they accept, they can sign in without you republishing.

Passwords

A credential principal puts a password on a path instead of (or as well as) an identity:

/*         viewer:letmein
/staging/* team:sekrit

The first line is whole-domain password protection—the classic use. The second protects just a section. Visitors get the browser's password prompt; scripts pass credentials the usual way:

curl -u viewer:letmein https://example.surge.sh/

The two kinds mix on one line, which is exactly what a protected path with automation wants—people sign in with Google, CI fetches with credentials:

/reports/*   collaborators ci-bot:s3cret

Notes

  • The AUTH file itself is never served—it's consumed by the platform, not published.
  • Because AUTH ships with your files, protection is versioned: rolling back a revision rolls back its rules too, and removing the file on the next publish removes the protection.
  • Sign-in lasts 12 hours per domain. Visiting /__surge/logout on your domain signs out, and the page a signed-in-but-not-allowed visitor sees offers the same switch—useful for changing accounts.
  • Removing someone takes effect on their next sign-in: update the rule (or remove the collaborator) and publish; existing sessions expire within 12 hours.
  • Serve protected projects over HTTPS (automatic on surge.sh subdomains, automatic certificates on custom domains) so nothing is exchanged in the clear.
  • A malformed rule stops the publish with a line-by-line explanation that names the fix—jane@example.com on its own suggests /* jane@example.com. Your project is never published with a policy you didn't write.
  • Legacy AUTH files—bare user:password lines with no path—keep working exactly as before, as shorthand for /* user:password.