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 Google sign-in
*@example.com Anyone at that domain Google sign-in
collaborators Anyone you've invited to this domain Google sign-in
user:password Whoever knows the password Browser password prompt, or curl -u

Identity principals ask visitors to sign in with Google—any Google account works, including Google Workspace; the people you name don't need a Surge account. If the email Google verifies matches the rule they're in, for 12 hours across the whole domain. 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 project:

/*   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-project 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.
  • Google sign-in lasts 12 hours per domain. Visiting /__surge/logout on your domain signs out—useful for switching Google 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—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.