The Authorization header has a fixed shape defined by RFC 7235: a scheme, a single space, then the credentials.
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...Almost every authentication bug that is not a key problem is a formatting problem in that one line.
What goes wrong
Duplicated scheme. Bearer Bearer eyJ… — a client prefixed a token that already carried its prefix. Produces a 401 with no useful message.
Quotes included. Copying "eyJ…" from a JSON config sends the quotes as part of the credential.
Unexpanded variables. Bearer ${API_TOKEN} when the shell or template never substituted. The parser here spots this pattern explicitly, because it is common and the resulting error never mentions it.
A newline in the value. Copying from wrapped terminal output. Some servers reject the request outright; others silently truncate.
Case. RFC 7235 makes the scheme case-insensitive. Many gateways match Bearer exactly anyway. Use the canonical casing.
Basic authentication
Basic encodes username:password as Base64. That is encoding, not encryption — anyone who sees the header reads the password with a single decode. This tool shows the decoded values when parsing, precisely to make that obvious.
Where an API uses Basic with an API key, the convention is key-as-username with an empty password, which is why the trailing colon matters: sk_live_abc: encodes differently from sk_live_abc.
Basic is acceptable over TLS. It is unacceptable anywhere else, and a long random token is a better credential than a password regardless.
Header versus query string
Always the header. Query strings are recorded in web server access logs, proxy logs, browser history and Referer headers sent to third parties. A key in a URL has leaked to more systems than you can enumerate. The cURL generator marks query-parameter authentication as a problem for exactly this reason.
Frequently asked questions
Bearer or ApiKey as the scheme?
Bearer if the credential is an OAuth token or a JWT — that is what RFC 6750 defines. For a static API key, a custom header such as X-API-Key is clearer: it signals that this is not an OAuth token and avoids implying refresh semantics that do not exist.
Is Basic authentication ever acceptable?
Over TLS, with a high-entropy random key as the username, yes — many payment APIs work this way. Never over plain HTTP, and never with a human-chosen password if you can avoid it.
Why does my header work in curl but not in my application?
Compare the exact bytes. The usual culprits are a trailing newline your HTTP client adds, a framework that lowercases or reorders headers, or a proxy stripping Authorization on redirect — curl drops it across hosts by default, and some clients do not.
How do I debug a header I cannot see?
Paste it into the auth header debugger, which checks for all of the above and decodes an embedded JWT's expiry and scopes.