Keep Bearer Tokens Out of URLs

A bearer token grants access to whoever presents it successfully. That makes its storage and transport path part of the authentication design. If an application places such a token in a URL, the credential can travel into systems that were built to record or process URLs rather than protect secrets.

The immediate request may still use HTTPS. The problem is what happens around that request: server access logs, reverse proxies, monitoring tools, browser history, support captures, and analytics pipelines can all handle URL data. A token copied into those places gains more exposure paths and can remain there long after the request finishes.

The practical rule is narrow: do not put bearer credentials in URL paths or query strings when a protected request field can carry them instead. This article explains the trust boundary behind that rule, the cases that need extra care, and a migration approach that does not treat HTTPS as a complete answer.

A bearer token is authority in a string

A bearer token is a credential whose possession is sufficient for the server to accept the authority represented by that token, subject to the server’s validation rules. The server may also check expiration, audience, scope, revocation state, or other properties, but it does not normally require the presenter to prove possession of a separate secret for each request.

Consider an API call shaped like this:

GET /account?access_token=<token>

The application may validate the token correctly. The transport connection may also be encrypted. Yet the token is now part of the request target.

Compare that with a conceptual request that carries the credential in an authorization field:

GET /account HTTP/1.1
Host: api.example.test
Authorization: Bearer <token>

Both requests deliver a credential to the application. The second form keeps the credential out of the URL, which reduces the number of ordinary URL-handling systems that can receive it.

This is exposure reduction, not invisibility. Servers, proxies, debugging tools, or compromised endpoints can still record headers. The control works because credentials can be given a narrower handling policy than URLs, not because headers are inherently secret.

URLs are commonly treated as recordable data

Web infrastructure needs request targets for routing, diagnostics, metrics, and troubleshooting. As a result, URL paths and query strings often cross operational boundaries.

A simple request can pass through several components:

client
  |
  v
edge proxy -> access log
  |
  v
application -> tracing or error report
  |
  v
downstream service

If the bearer token sits in the URL, each component that records the request target may receive a copy. Those copies can then have different access controls and retention periods from the credential store that was supposed to protect authentication material.

This changes the threat model. An attacker no longer needs access to the application’s primary token store if a lower-privilege logging or support system contains reusable tokens. An accidental log export can also expose credentials without exposing the database that issued them.

Keeping the token out of the URL removes this specific propagation path. It does not protect against a component that deliberately records authentication headers or full request bodies.

HTTPS protects transit, not every endpoint copy

HTTPS protects HTTP data against network observers under the assumptions of TLS and correct certificate validation. That includes the path, query string, headers, and body while they travel inside the encrypted connection.

Once a request reaches a TLS endpoint, the endpoint must process the decrypted HTTP message. A reverse proxy that terminates TLS can therefore see the request target. So can the application after the request is forwarded.

This distinction matters:

network observer
      X
      | encrypted TLS connection
      v
TLS endpoint -> can process URL and headers

HTTPS is still required for bearer credentials sent over the web. Moving a token from a URL into a header does not replace transport protection. The two controls address different risks: TLS protects data in transit between trusted endpoints, while credential placement reduces accidental propagation through URL-oriented systems.

Browser URLs create extra exposure paths

Browser-based flows need particular care because the browser exposes URLs to features beyond the network request itself.

A URL may enter browsing history. Users may copy it into chat, tickets, documents, or screenshots. Browser extensions can have permissions that expose browsing information. Application code can also pass URL data into analytics or error reporting.

Navigation creates another boundary. A browser can send a Referer request header during some navigations and subresource requests, subject to the active referrer policy and browser rules. Modern referrer policies often limit cross-origin detail, but a security design should not depend on every deployment retaining a particular policy forever.

The safer approach is to avoid making a reusable bearer credential part of a browser URL in the first place.

Some web protocols do use short-lived values in redirect URLs as part of a defined flow. Do not generalize the rule into rewriting standards-based protocols. Follow the protocol’s security requirements and use maintained libraries. The concern here is application-designed bearer credentials that can be placed in a less exposed request field.

Put API bearer tokens in the authorization field

For HTTP APIs that use bearer access tokens, the Authorization request header is the conventional location:

Authorization: Bearer <token>

The application should parse and validate that field using its authentication middleware or protocol library. Logging configuration should redact or omit authentication fields before events leave the request-handling boundary.

The header placement provides a clean operational distinction:

URL fields              -> useful for routing and request diagnostics
Authorization field     -> credential, redact or omit

That distinction makes policy easier to express. A logging pipeline can keep request paths while dropping the authorization value. A tracing library can capture route templates without copying credentials. Security review can also identify authentication material by a defined field rather than searching arbitrary URLs.

Do not move a bearer token into a custom header merely to make it look different. Use the protocol-defined field when the authentication scheme supports it.

Request bodies are not a universal replacement

A developer who removes a token from the query string may consider putting it in a form field or JSON body. That can be appropriate only when the protocol defines such placement and the endpoint semantics support it.

Bodies have their own exposure paths. Debug middleware, application logs, tracing systems, and error reports may capture them. Some request methods and intermediaries also make body-based authentication awkward or unsupported.

The defensive decision is not “URLs bad, bodies secret.” It is to use the authentication mechanism’s defined credential channel and configure every component on that path to treat the credential as sensitive.

For standard bearer-token HTTP authentication, that normally means the authorization header over HTTPS.

Do not accept several token locations without a reason

Supporting a token in a header, query parameter, and body at the same time seems flexible. It also creates ambiguous behavior.

Suppose a request contains two different credentials:

Authorization: Bearer token-A
?access_token=token-B

The application now needs a precedence rule. A proxy or middleware layer may use a different rule. Logs may record one credential while authentication uses another. Security tests must cover every accepted location.

A narrower interface is easier to reason about:

accepted credential location: Authorization header
all other token locations: rejected

During a migration, temporary compatibility may require more than one location. Define the precedence explicitly, measure remaining legacy use without recording token values, and remove the old path on a planned date. Do not leave the fallback indefinitely because a few clients might still depend on it.

Redaction is defense in depth, not permission to use URLs

A common response to URL credentials is to configure logs to replace the token value:

/account?access_token=[REDACTED]

Redaction is useful, but it is not a substitute for safer credential placement.

The token may pass through several systems before reaching the component that performs redaction. A new proxy, tracing agent, exception handler, or debug feature can record the original request target. Redaction rules can also miss renamed parameters or alternate routes.

Use both controls where appropriate: keep bearer tokens out of URLs, and configure logging systems to avoid recording credentials in accepted authentication fields.

Redaction should happen as close to collection as practical. A token copied into a central log store and removed later has already crossed the boundary the control was meant to protect.

Handle existing URL tokens as exposed credentials

When a production system has historically accepted bearer tokens in URLs, migration requires more than changing new client code.

First, stop issuing new links or examples that place reusable tokens in URLs. Update clients to use the supported authentication field. Then remove URL-token acceptance once compatibility permits.

Next, inspect the data flows that may have retained old URLs. Relevant systems can include access logs, tracing platforms, analytics, support exports, and application error reports. Do not copy raw tokens into a new inventory while performing this review.

Whether existing tokens need rotation or revocation depends on their sensitivity, lifetime, scope, evidence of exposure, and the systems that recorded them. Long-lived reusable credentials found in broadly accessible logs deserve a different response from already expired, tightly scoped tokens in a restricted store.

Log deletion can reduce future exposure, but it does not prove that a credential was never copied elsewhere. Credential rotation closes that uncertainty when the risk justifies the operational cost.

Test the whole request path

A unit test that checks token parsing is not enough to verify credential handling.

Send a test request through the same proxy and middleware path used in production, using a clearly synthetic credential. Confirm that the application accepts the authorization field and rejects unsupported URL placement. Then inspect the resulting access logs, traces, and error events.

The expected result is straightforward:

request path visible
route metadata visible
bearer value absent

Also test failure paths. Authentication errors, upstream timeouts, malformed requests, and exception handlers often use different logging code from successful requests.

Use only synthetic values for these tests. A production credential should not be introduced into observability systems merely to check whether redaction works.

Keep the credential path narrow

Bearer tokens are easiest to protect when their path through the system is explicit. Send API bearer credentials over HTTPS in the authentication field defined by the protocol, keep them out of paths and query strings, and configure logs and traces to omit their values.

This control reduces accidental copies and narrows the set of systems that need access to reusable credentials. It does not compensate for stolen tokens, weak token validation, excessive scopes, long lifetimes, compromised clients, or components that intentionally record sensitive headers.

The next practical step is to trace one authenticated request from client to application and list every component that can observe the credential. If the token appears in a URL or an ordinary diagnostic field, move it onto the intended authentication path and verify the change at each boundary.