Card 04/ 12
Bearer Tokens and the Authorization Header
Whoever holds a bearer token is let in, so it travels only over TLS and only in one header.
A bearer token is a credential that grants access to whoever presents it, the bearer, with no further proof. It is usually issued to an app acting for a user, by an authorisation server, and sent in the Authorization: Bearer header. Because holding it is enough, it must travel only over TLS, the encryption behind HTTPS, and must be short-lived, so a stolen one stops working soon.
A bearer token works like a cinema ticket: whoever holds it gets in, and nobody checks a name. The comparison breaks on how often it is checked, since a cinema looks at a ticket once at the door and an API checks the token on every request.
GET /v1/orders HTTP/1.1
Authorization: Bearer 7Kq2mX9vT4pL8rWz3nB6
Host: api.example.com
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="api", error="invalid_token"What proves the caller. The token itself. It may be opaque, a random string the API looks up at the issuer, or self-contained, such as a JWT that carries signed claims the API can check without asking anyone.
Where it travels. In the Authorization header with the Bearer scheme, defined by RFC 6750. A 401 response carries WWW-Authenticate: Bearer so the client knows which scheme is expected and, through error, why the token was refused.
Which client it suits. Apps acting for a user, such as a mobile app or a third-party integration, where the token was issued after the user signed in and stands for what the user allowed. How the app obtains it is the subject of OAuth.
How access is cut off. Each token expires, typically within minutes to an hour, and the issuer can revoke it. An opaque token stops working as soon as the issuer revokes it; a self-contained one keeps working until it expires unless the API checks more.
So send bearer tokens only in the Authorization header over HTTPS, and keep them short-lived.
← → move through sections and cards