Skip to main content

Basic Auth


This modules enforces HTTP Basic Authentication in front of you endpoints. Requests with a valid username and password will be sent to your upstream service, all others will be rejected with a 401 Unauthorized response.

Example Usage

Allow requests from two different users, each with a different password.

ngrok http 80 --basic-auth "username1:password1" --basic-auth "username2:password2"


This module enforces HTTP Basic Auth as defined by RFC 7617.

Requests with a valid username and password are sent to the upstream application. All other requests receive an HTTP 401 response.

Multiple Credentials

You may specify multiple username/password credential pairs. A request is allowed if it matches any of the configured credentials.

ngrok http 80 \
--basic-auth "user1:password1" \
--basic-auth "user2:password2"


The HTTP Basic Auth realm is always 'ngrok'. It may not be configured.

Basic Auth on Upstream Service

If your upstream service also enforces HTTP Basic Auth, it is not recommended to use this module with it. Instead, you should choose to either not use this module or to disable http basic auth enforcement on your upstream service. If you absolutely must use HTTP Basic Auth on both your ngrok endpoint and your upstream service, you have two options:

  1. Ensure that the username/password credentials enforced by ngrok and those enforced by the upstream service are identical. If you don't, no requests will ever be successful because they will always be rejected by either your ngrok endpoint or the upstream service.

  2. Use the Request Headers module to rewrite the authorization header to the value expected by the upstream service. For example, if you want to accept requests with credentials of "username:password, but the upstream service expects credentials of "Aladdin:open sesame", you could use the following command. Keep in mind that you need to base64 encode the username and password for the upstream service.

ngrok http 80 \
--basic-auth "username:password" \
--request-header-remove "authorization" \
--request-header-add "authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ=="



CredentialsA list of username/password pairs specified as 'username:password'. Passwords must be at least 8 characters and more than 128 characters.

Upstream Headers

This module does not add any upstream headers.


CodeHTTP StatusError
no ngrok error code401This error is returned if a request is disallowed.


This module does not populate any fields in events. When this module is enabled, it populates the following fields in the http_request_complete.v0 event:




Basic Auth is not a supported HTTPS Edge module yet.


This module is available on all plans.

Try it out

Start ngrok in one terminal:

ngrok http --domain --basic-auth "falken:joshuahunter2"

In another terminal, curl that endpoint.

Without any credentials:


401 Unauthorized

With incorrect credentials:

curl --user "foo:bar"

401 Unauthorized

And finally with valid credentials:

curl --user "falken:joshuahunter2" -I

HTTP/2 200