Set up Basic Auth

Basic Authentication (Basic Auth) lets you protect your instance with a username and password. It is useful for restricting access to staging environments, development previews, or internal projects before going live.

How it works

When Basic Auth is enabled:

1. Incoming requests must include an Authorization header with valid credentials
2. Credentials are validated against your configured username/password pairs
3. After successful validation, the Authorization header is removed from the request before it reaches your application
4. An Auth-User header containing the authenticated username is added to the request

This ensures credentials are not exposed to your application or logged downstream.

Configuration

General behavior

• You can add multiple credentials (username + password pairs).
• Basic Auth can be enabled or disabled at any time.
• Without at least one credential, Basic Auth cannot be enabled.
• Credentials can be edited or removed after being added.
• Enabling Basic Auth also affects Commerce Intelligence and Performance Audits — automated audits cannot run while Basic Auth is active.

Basic Auth & other security features

Order of processing security features

Security feateures processing sequence is describled in separete document.

Basic Auth & CDN

When Basic Auth is active:

• All requests must include valid credentials (username + password), except for requests coming from IPs on the Allowed list.
• CDN caching applies — responses are cached at the edge after authentication validation. The Authorization header is stripped before cache lookup, so the cache key is based on URL alone.
• Performance audits cannot be conducted, since automated tools cannot bypass authentication.

When Basic Auth is disabled:

• If CDN was previously enabled, caching behavior remains unchanged.