Header Authentication
Require HTTP headers or Basic Auth to access your tunnels
Overview
Header Authentication policies require clients to provide specific HTTP headers or Basic Authentication credentials to access your tunnel. Perfect for API authentication, internal tools, and simple access control.
Key Features
- • HTTP Basic Authentication (username/password)
- • Custom header requirements (API keys, tokens)
- • Multiple header conditions (AND logic)
- • Bearer token support
Configuration Schema
| Field | Type | Description |
|---|---|---|
| auth_type | "basic" or "header" (required) | Authentication method:
|
| username | String (required for "basic") | Username for Basic Auth. Required when auth_type is "basic". |
| password | String (required for "basic") | Password for Basic Auth. Required when auth_type is "basic". |
| required_headers | Array of objects (required for "header") | List of required HTTP headers. Each header object has:
|
How It Works
- • Basic Auth: Validates HTTP Basic Authentication using the
Authorizationheader. Username and password must match exactly. - • Header Auth: Checks for required HTTP headers. If a header value is specified, it must match exactly. If no value is specified, the header just needs to be present.
- • All required headers must be present and match (if values are specified) for the request to be allowed
- • Failed authentication results in a 403 Forbidden response
Configuration Examples
Example 1: HTTP Basic Auth
{
"name": "Simple Password Protection",
"auth_type": "basic",
"username": "dev",
"password": "dev-password-123"
}Browser will prompt for username and password.
Test with curl:
curl -u dev:dev-password-123 https://myapp.tnl.ngsrv.comExample 2: Custom API Key
{
"name": "API Key Required",
"auth_type": "header",
"required_headers": [
{
"name": "X-API-Key",
"value": "sk_live_abc123xyz789"
}
]
}Clients must send the API key in a custom header.
Test with curl:
curl -H "X-API-Key: sk_live_abc123xyz789" https://myapp.tnl.ngsrv.comExample 3: Bearer Token
{
"name": "Bearer Token Auth",
"auth_type": "header",
"required_headers": [
{
"name": "Authorization",
"value": "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
]
}Require a specific Bearer token.
Example 4: Multiple Headers (AND Logic)
{
"name": "Multi-Header Auth",
"auth_type": "header",
"required_headers": [
{
"name": "X-API-Key",
"value": "secret-key-123"
},
{
"name": "X-Client-ID",
"value": "client-456"
}
]
}All headers must be present and match.
Example 5: Webhook Secret Verification
{
"name": "Stripe Webhook Signature",
"auth_type": "header",
"required_headers": [
{
"name": "Stripe-Signature",
"value": "t=1614556800,v1=abc123..."
}
]
}Verify webhook signatures for services like Stripe.
Common Use Cases
Internal Tools
Password-protect development dashboards and admin panels with Basic Auth.
API Testing
Test API endpoints that require API keys or Bearer tokens locally.
Webhook Debugging
Verify webhook signature headers during local development.
Client Demos
Share previews with clients using simple username/password protection.
B2B API Integration
Test partner API integrations that require custom authentication headers.
How to Use
Step 1: Create Policy
Go to Dashboard → Security → Header Authentication
- Click "Create Policy"
- Choose authentication type (Basic or Header)
- Enter credentials or header requirements
- Save the policy
Step 2: Apply to Tunnel
ngsrv http 3000 --policy ngsrv_auth_ABC123Step 3: Test Authentication
For Basic Auth:
curl -u username:password https://myapp.tnl.ngsrv.comFor Custom Headers:
curl -H "X-API-Key: your-key" https://myapp.tnl.ngsrv.comBest Practices
✅ Use Strong Passwords
Generate random passwords, don't use "password" or "admin".
✅ Rotate Credentials
Change API keys and passwords regularly for security.
⚠️ Don't Share Credentials
Create separate policies for different users or teams.
❌ Don't Commit Secrets
Never commit passwords or API keys to version control.
💡 Combine with IP Whitelist
Use both IP whitelisting and header auth for defense-in-depth.