Header
Sec-WebSocket-Key
Learn how the Sec-WebSocket-Key header provides a random key for WebSocket handshake validation. Understand the upgrade process and security implications.
TL;DR:
Sec-WebSocket-Keyis the client side of the WebSocket handshake challenge. It gives the server something unique to prove it really handled this upgrade request.
What The Header Is Doing
When a browser opens a WebSocket, it does not jump straight to raw socket frames. It starts with an HTTP request that asks to upgrade the connection. Sec-WebSocket-Key is part of that request.
Example:
GET /chat HTTP/1.1
Host: server.example.com
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==
Sec-WebSocket-Version: 13The key is a random base64 value generated by the client. The server must transform it and return the expected result in Sec-WebSocket-Accept.
Why The Key Matters
This header is not an auth token and it is not a secret shared between client and server. Its job is narrower:
- tie the handshake response to this exact request
- stop old or cached responses from validating accidentally
- confirm the server understands the WebSocket upgrade process
That is why the header exists even though the browser is already talking to the server over HTTP.
The Important Practical Consequence
You cannot fake a browser WebSocket handshake with ordinary frontend request APIs like fetch() or XMLHttpRequest. Browsers reserve this flow for the WebSocket API and generate the handshake headers themselves.
That is why you do not usually “set Sec-WebSocket-Key manually.” The browser owns it.
What Server Code Has To Do
On the server side, the implementation usually:
- verifies the key is present and well formed
- appends the WebSocket GUID
- hashes and base64-encodes the result
- returns that value in
Sec-WebSocket-Accept
Libraries usually do this for you, but understanding the header helps when a reverse proxy or custom server breaks the handshake.
What To Check During Debugging
If a WebSocket upgrade fails:
- confirm the request really included
Upgrade: websocket - confirm
Sec-WebSocket-Keyis present - confirm the server answered with
101 Switching Protocols - confirm the response includes the matching
Sec-WebSocket-Accept
That sequence is usually faster than jumping into application code immediately.
Related Headers
Frequently Asked Questions
What is Sec-WebSocket-Key?
It is a random base64 value the client sends as part of the WebSocket opening handshake.
How does the server respond to Sec-WebSocket-Key?
The server transforms it into `Sec-WebSocket-Accept`, which proves the server actually processed the upgrade request.
Why is Sec-WebSocket-Key needed?
It helps prevent stale or fake upgrade responses from being mistaken for a valid WebSocket handshake.
Can I set Sec-WebSocket-Key manually?
In browsers, no. The WebSocket API generates it automatically and does not let JavaScript set it directly.