Skip to content

Header Authentication

Require an API key or shared header on every request to a tunnel. Requests without it are rejected before they reach your machine. No code required.

Summary

Header Authentication requires every request to carry headers you name, with the values you set. Localport checks them before the request reaches your service. It fits machine callers that send a fixed value on every call: an API client, a script, a partner integration, a service behind an access proxy.

How header authentication works#

A request is admitted when it carries every header you listed, each with the exact value you set. Anything else is refused before it is routed.

Rules combine with AND. A request carrying four of your five headers is refused exactly like one carrying none.

Rules apply to HTTP and HTTPS traffic, on a tunnel and on a fleet.

Add header rules#

Each row is one header and the value every request must carry.

1. Open the tunnel's Settings and find HTTP Protection.

2. Turn on Header Authentication.

3. Pick a header from the list, or choose Custom header and type your own.

4. Enter the Value that requests must carry.

5. Click Save.

A tunnel holds up to five rules. Editing them requires the Admin role, and the values are encrypted at rest.

Rule requirements#

  • A value is required. A rule naming a header with no value is refused.
  • One rule per header. The same name twice is refused.
  • Names are HTTP tokens, up to 64 characters.
  • Values are up to 1 KB, which fits an access-proxy client id and secret together.
  • Connection headers are unavailable: Host, Content-Length, Connection, Transfer-Encoding and Upgrade.
  • Authorization is unavailable while Basic Authentication is on, in both directions.

Turning the setting on with no rules is refused.

Calling a protected tunnel#

A caller sends the headers with the request:

curl -H "X-API-Key: 9f2c1ab34de5f607" https://example.eu.localport.dev

Header names match without regard to case, so x-api-key satisfies a rule written X-API-Key. Values match exactly.

Your application receives ordinary requests. There is no middleware to add, and nothing to remove when you turn the setting off.

Rejected requests#

A request missing a header, or carrying the wrong value, is answered with 401 Unauthorized and never reaches your machine. The response names no header and no rule.

Changing rules#

Saving replaces the whole rule set. The change applies immediately, with no restart and no reconnection, and the next request on any connection is checked against the new rules.

Rotating a value#

A header holds one value, so a rotation runs as a staged swap:

1. Have callers start sending the new header alongside the old one. No rule checks it yet.

2. Add the rule for the new header.

3. Remove the rule for the old header.

4. Have callers stop sending the old header.

Five rules leaves room to overlap. Frequent rotation is a sign the endpoint has outgrown a shared value and wants Remote Access, where each caller holds a certificate of its own.

What Localport reads#

Only the headers you named are read, and only to compare them with the values you set. The request body is never read, and nothing else in the request takes part in the decision.

Your service receives the request unchanged, headers included.

Limitations#

  • A header value is static, so anyone who captures a request holds it until you rotate. Where a provider signs its requests, webhook verification is the stronger check, because a signature covers the body.
  • Every caller sends the same value, so callers cannot be told apart and one cannot be revoked on its own. That needs Remote Access.
  • Rules apply to HTTP and HTTPS. A TCP or TLS tunnel carries no headers, so restrict it with an IP allowlist.

Frequently asked questions#

How do I require an API key on my tunnel?

Turn on Header Authentication under HTTP Protection in the tunnel's settings, add a rule naming the header, such as X-API-Key, and the value it must carry, then save. Requests without that exact header and value are rejected before they reach your machine.

Can I require more than one header?

Yes, up to five. All of them must match, because rules combine with AND. A request carrying some but not all of them is refused exactly like one carrying none.

Are header names case-sensitive?

Names are not. A caller sending x-api-key satisfies a rule written X-API-Key. Values are matched exactly, including case.

Why can I not check the Host or Content-Length header?

Those belong to the connection, not to the caller, so a rule on one would test the transport instead of who is asking. Host, Content-Length, Connection, Transfer-Encoding and Upgrade are all unavailable.

Why can I not use the Authorization header with basic auth on?

Basic auth already reads that header. It is refused in both directions: no Authorization rule while basic auth is on, and no turning basic auth on while such a rule exists.

How do I rotate a header value without downtime?

Have callers send the new header first, while no rule checks it. Then add the rule for the new header, remove the rule for the old one, and have callers stop sending the old header. Saving replaces the whole rule set, so a header cannot accept two values at once.

Is this as safe as signature verification?

They solve different problems. A header value is static, so anyone who captures a request holds it until you rotate. A signature is computed over the body and cannot be reused for different content, so where a provider offers one, use webhook verification.

Does my app need to check the header as well?

Not for the tunnel to protect it, since the check runs before the request is routed. Checking at your own boundary too is sound practice in production, because an application's defences should not depend on which path traffic arrived by.

What does a refused caller see?

401 Unauthorized, naming no header and no rule. Nothing reaches your machine.

Previous Webhook Verification Next Remote Access