What are HTTP headers — and why your key rides there, not in the URL

Here's something odd at first glance: almost every API asks you to send your key as a header, not just tack it onto the URL. Technically the second option is simpler — and it works. Almost nobody does it, and the reason is surprisingly mundane: URLs get written down. Into server logs, into browser history, into analytics. Headers don't.
So let's unpack what headers actually are. After this, half the lines in API docs stop looking like code.
What it is, in one line
Headers are a note attached to your request, separate from the content itself.
Picture a parcel. The address on the box is the URL — where the request goes. What's inside is the request body. And stuck to the side are little labels: "fragile", "for: Ivanov", "prepaid". Those are headers: not the cargo, but information about the cargo and the sender.
The format is boringly simple — Name: value, one pair per line:
Content-Type: application/json
Authorization: Bearer sk-abc123
That's it. No magic. Just a list of notes the server reads before it touches the content.
What a live request looks like
When you call an API from code, roughly this goes out:
POST /v1/messages
Content-Type: application/json
Authorization: Bearer sk-abc123
Accept: application/json
{"text": "hello"}
First line — what we're doing and where. Then the headers. Then a blank line, and after it the body. Your browser, curl and your code all assemble exactly this; you just don't normally see it.
Open DevTools → Network in your browser, click any request and find the Headers tab — same thing, just prettier. That's the first place to look when "the request looks right but doesn't work".
Why the key rides in a header, not in the URL
Now the surprising part. You could send the key like this: /v1/messages?key=sk-abc123. The server reads it, everything works. But URLs have a property headers don't: they get saved everywhere.
- Web servers write the full URL of every request into their logs. Your key ends up in a text file several people read.
- The browser puts the address in history and offers it in autocomplete.
- Follow a link and the address can leak to another site in the
Refererheader. - URLs are easy to copy and paste into a chat — key included.
A header doesn't reach history or the address bar, and isn't logged by default. Hence the rule: secrets go in headers, everything else can go in the URL. It's also why you shouldn't keep keys in frontend code — a header hides your key from logs, not from someone with DevTools open.
Four headers you'll meet first
Content-Type — what language the body is written in. application/json means "there's JSON inside". Leave it out or get it wrong, and the server will dutifully try to read your JSON as plain text and return a parse error. That's the number-one cause of mysterious 400s for beginners.
Authorization — who you are. Usually in the form Bearer your_key. Forget the word Bearer, add a stray space, or let undefined slip in, and you get a 401 "the server doesn't recognise you".
Accept — what you want back. Say application/json and a server that speaks both JSON and XML will hand you JSON.
User-Agent — what sent the request: a browser, a script, a bot. Some sites serve different content based on it; some block scripts by it.
Response headers: the server writes a note too
The exchange goes both ways. The server answers with its own headers, and they explain a pile of things that otherwise look like witchcraft:
Content-Type— what it sent. The browser uses it to decide: render the page or download the file.Set-Cookie— "remember this and send it back". That's how cookies work.Cache-Control— how long the answer counts as fresh. This is where "I updated the site but users see the old version" comes from.Access-Control-Allow-Origin— who's allowed to call this API from a browser. No header, and you hit a CORS error.
How is a header different from a URL parameter?
A parameter (?page=2) is part of the address: visible, saved in history and logs, easy to copy. A header travels alongside and by default sticks nowhere. So the URL carries which page you want, and the header carries who you are and the format of the exchange.
Can I invent my own header?
Yes, and people do it constantly. Plenty of APIs expect the key in their own header like x-api-key. One rule: don't guess the format — open that API's docs and match it literally. Case doesn't matter; the word Bearer very much does.
Why won't the browser let me set some headers?
The browser fills some headers itself and blocks JavaScript from touching them — Host, Referer, the real User-Agent. Otherwise any page could pretend to be another site or another browser. From server-side code there's no such limit: there, the whole request is yours.
The AI Architect 2027 course: step by step from computer basics to your own app and first customers. 543 short lessons on your phone.





