examples · errors · 7 / 19

7. 401 - malformed bearer token

what this error means

The Authorization header arrived, but it does not match the expected shape Bearer <token>. Either the Bearer prefix is missing, the token bytes are not a valid token, or there's stray punctuation.

what triggers it

An Authorization header that's missing the Bearer prefix.

POST /v1/tenants/:t/sql - malformed header

curl -X POST "https://$OC_HOST/v1/tenants/$OC_TENANT/sql" \
  -H "Authorization: not-a-real-bearer" \
  -H "Content-Type: application/json" \
  -d '{"sql": "SELECT 1"}'

the canonical response body

{
  "error": "unauthorized",
  "message": "Authorization header must be 'Bearer <token>'",
  "retry": false
}

how to recover

Prefix the token with the literal word Bearer (capital B, single space).
Echo the env var to confirm it has the actual token bytes, not "$OC_TOKEN" as a literal string.
Strip newlines from a token pasted out of a wrapped terminal - some shells inject \\r.
retry: false - the header is wrong, not the engine.

common upstream causes

Token sent without the Bearer prefix.
Lowercase bearer from a snippet - the parser is case-sensitive on the scheme name.
Smart-quote characters from a doc copy-paste (" vs ").
Trailing whitespace or newline pulled in from a file read.
Two tokens concatenated by accident (env var set twice).