What is a bearer token, and how do you use it to call a protected API? This guide explains bearer token authentication in simple terms, with a clear example and step-by-step explanation of how tokens are sent using HTTP.
A token is something that one party gives to another to prove a claim or grant access. A simple example is an ID card issued by a city to a citizen. The card proves the person’s identity and allows access to certain services.
An ID card is tied to a specific person. It is only valid if the photo matches the person using it. Some tokens do not have this restriction. For example, a car key can be given to a repair shop. Anyone who has the key can open the car.
The term bearer means holder or possessor. Whoever holds the token can use it. It is not tied to a specific identity. Possession of the token is enough to gain access.
In IT security, tokens are used for authentication (who you are) and authorization (what you can access). Tokens can represent users, systems, or permissions. Besides hardware tokens such as crypto cards and PIN generators, tokens are often simple pieces of data.
Some tokens contain information that the receiver can read and verify:
Other tokens act as placeholders for sensitive data such as credentials. Their value has no meaning by itself and is not self-contained. To keep them secure, they are usually long, random strings that are hard to guess.
Let's see how bearer token authentication works in a simple HTTP API example.
The example involves three parties: a cookie monster (client), a cookie factory (API), and an authentication service.
The story begins with the cookie monster having only one cookie left and needing more. It sends a request to the cookie factory API to get new cookies.
The HTTP request looks like this:
GET /cookies HTTP/1.1The cookie factory only serves cookies to authorized clients. Since the request has no authorization, the API responds with 401 Unauthorized and rejects the request.
The response also tells the monster how to authenticate and where it applies. It looks like this:
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="CookieFactory"Right… the cookie monster remembers that it only gets cookies when authorized. So it takes a short detour to the authentication service. There, it must prove its identity using a username and password.
The monster’s request looks like this:
POST /issue HTTP/1.1
{
"user":"CookieDestroyer",
"password":"U+1F36A"
}The authentication service checks the credentials and accepts them. The CookieDestroyer is known there as a cookie monster. All requirements to issue a bearer token are now fulfilled.
The response contains the bearer token in the HTTP body:
HTTP/1.1 200 OK
{
"token":"S0VLU0UhIExFQ0tFUiEK"
}Great, now the cookie monster can finally request new cookies. It sends another request to the API. This time, it includes the bearer token.
The bearer token is sent in the HTTP Authorization header.
GET /cookies HTTP/1.1
Authorization: Bearer S0VLU0UhIExFQ0tFUiEKThe factory sees that the request includes a bearer token. Before it can trust the token, it must validate it.
The cookie factory asks the authentication service for help because the token has no cryptographic protection. Tokens with a signature can be verified locally. Simpler tokens must be checked by a trusted service.
To validate the token, the cookie factory sends it to the authentication service.
The validation might look like this:
POST /validate HTTP/1.1
{
"token":"S0VLU0UhIExFQ0tFUiEK"
}The authentication service recognizes the token because it issued it just seconds ago. The token is still valid and the service confirms that.
The authentication service responds to the cookie factory with a success message:
HTTP/1.1 200 OKThe cookie factory keeps the connection to the monster open and sends the response: cookies.
Finally the cookies:
HTTP/1.1 200 OK
Content-Type: application/json
["Cookie","Cookie","Cookie"]The cookie monster has successfully made an authorized API request using a bearer token. It receives plenty of cookies and is happy.
As a conclusion: if there are cookies, monsters will always find a way.
This example showed step by step how bearer token authorization works. If a protected API is called without a token, the client receives a response that authorization is required. To get a token, the client must prove its identity. If authentication succeeds, a bearer token is issued. If the token is not self-contained, the API must validate it with an authentication service before processing the request.
The extra request to the authentication service can be avoided by using a self-contained token such as a JSON Web Token (JWT) with a digital signature. The trade-off is higher complexity due to cryptography. In both cases, bearer tokens allow the holder to access the API.
Bearer tokens are commonly used with OAuth2, JWTs, and API keys. API connections should always be protected with HTTPS (TLS) so attackers cannot intercept the token during transmission.