Base64 Encoding in HTTP Headers

← Back to Blog

Base64 Encoding in HTTP Headers

· 5 min read

Why HTTP Headers Use Base64

HTTP/1.1 protocol specifies that header field values must be ASCII printable characters (RFC 7230) and cannot contain newlines. This restriction means any value containing binary data or non-ASCII characters must be encoded before being placed in HTTP headers. Base64 is the standard solution satisfying this requirement: it converts any binary data to a safe ASCII string.

HTTP/2 and HTTP/3 improved header transmission efficiency through header compression (HPACK/QPACK), but character restrictions on field values remain largely compatible with HTTP/1.1. Therefore Base64 usage in HTTP headers remains equally common even with modern protocols.

The Authorization Header

The Authorization header is the most common place Base64 is used in HTTP. HTTP Basic Authentication format: Authorization: Basic [Base64(username:password)]. When the server responds with 401 Unauthorized, it tells the client that Basic Auth is required via WWW-Authenticate: Basic realm="API".

# 手动构建 Authorization 头部
# Manually construct Authorization header
username="[email protected]"
password="MySecretPass123"
credentials=$(echo -n "${username}:${password}" | base64)
echo "Authorization: Basic ${credentials}"
# Authorization: Basic dXNlckBleGFtcGxlLmNvbTpNeVNlY3JldFBhc3MxMjM=

# 使用 curl / Using curl
curl -H "Authorization: Basic dXNlckBleGFtcGxlLmNvbTpNeVNlY3JldFBhc3MxMjM=" \
  https://api.example.com/v1/resource

# curl 自动处理 / curl handles automatically
curl -u "[email protected]:MySecretPass123" https://api.example.com/v1/resource

Bearer Tokens and JWT

Bearer Token authentication scheme (OAuth 2.0) format: Authorization: Bearer [token]. When the token is a JWT, the entire JWT string (composed of three Base64URL-encoded parts) is the Bearer Token value. For example: Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIn0.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c.

Note that JWT uses Base64URL (not standard Base64), so + and / characters will never appear in a JWT. If you see these characters in a JWT, it indicates the JWT is malformed or uses a non-standard implementation.

Content-Disposition and Filename Encoding

The Content-Disposition header is used to specify filenames. When a filename contains non-ASCII characters (like Chinese filenames), special encoding is required. RFC 5987 defines the filename* parameter format using UTF-8 charset and percent-encoding; older implementations use RFC 2047's B (Base64) or Q (quoted-printable) encoding.

# RFC 5987 方式（现代，推荐）
# RFC 5987 approach (modern, recommended)
Content-Disposition: attachment; filename*=UTF-8''%E4%B8%AD%E6%96%87%E6%96%87%E4%BB%B6.pdf

# RFC 2047 Base64 方式（旧式，部分客户端仍使用）
# RFC 2047 Base64 approach (legacy, still used by some clients)
Content-Disposition: attachment; filename="=?UTF-8?B?5Lit5paH5paH5Lu2.pdf?="

# 兼容性写法（同时提供两种格式）
# Compatibility approach (provide both formats)
Content-Disposition: attachment;
  filename="=?UTF-8?B?5paH5Lu2.pdf?=";
  filename*=UTF-8''%E6%96%87%E4%BB%B6.pdf

Proxy-Authorization and Proxy-Authenticate

Proxy server authentication uses the same Base64 mechanism as HTTP Basic Auth, but uses different headers: Proxy-Authorization: Basic [Base64(username:password)] and Proxy-Authenticate: Basic realm="proxy". This is common in enterprise internal networks using authenticated HTTP proxies.

When configuring applications to use a proxy, proxy credentials are typically provided in URL format: http://username:[email protected]:8080. Many HTTP client libraries automatically parse this format and generate the corresponding Proxy-Authorization header (including Base64 encoding).

Base64 in Custom Headers

API developers sometimes use Base64-encoded data in custom headers (like X-API-Key, X-Auth-Token). There's often no particular technical reason — it's just a convention. If your API accepts such headers, document clearly whether the header value requires Base64 encoding and which variant (standard Base64 or Base64URL).

A common pattern is passing JSON objects (Base64-encoded) in custom headers. For example: X-User-Context: eyJ1c2VySWQiOiIxMjMifQ== (Base64 encoding of {"userId":"123"}). This pattern allows passing structured data in HTTP headers without an additional JSON deserialization step (since header parsing typically only handles strings).

Debugging Base64 in HTTP Headers

When debugging API issues, you often need to inspect Base64 values in HTTP headers. Browser developer tools (Network tab) display raw Base64 values, which you can copy to our online tool for immediate decoding. For command-line debugging, curl -v displays complete request and response headers.

# 显示请求和响应头部（包括 Authorization）
# Display request and response headers (including Authorization)
curl -v -u "user:pass" https://api.example.com/endpoint 2>&1 | head -30

# 解码 Authorization 头部中的 Base64
# Decode Base64 in Authorization header
AUTH_HEADER="YWRtaW46c2VjcmV0"
echo "${AUTH_HEADER}" | base64 --decode
# admin:secret

Try the online tool now — no installation, completely free.

Open Tool →