Access Tokens and Refresh Tokens Explained
What access tokens and refresh tokens are, how the two work together, how JWTs differ from opaque tokens, and what a server must check before trusting one.
· 8 min read
When you sign in to an app, you type your password once. Yet every request the app makes afterwards, such as loading your messages or saving a setting, also has to prove who you are. Sending the password each time would be dangerous, so the app sends a token instead.
This article explains what an access token is, why it usually comes with a refresh token, what is inside a JWT, and what a server has to check before it believes one.
What an access token is
An access token is a string that an API accepts as proof that the caller is allowed to do something. The app receives it after the user signs in and attaches it to each request:
GET /api/messages
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...The word Bearer matters. It means that whoever holds ("bears") the token can use it. The API does not ask for anything else. A bearer token is like a cinema ticket: the person at the door checks the ticket, not your identity.
That one property drives almost every rule about tokens:
- A stolen token works for the thief exactly as it works for the real user.
- So tokens must be hard to steal, and must stop working quickly if they are.
A hotel key card
A useful way to picture it is a hotel.
| Hotel | Token world |
|---|---|
| You show your passport at reception once | You sign in with your password once |
| You get a key card | The app gets an access token |
| The card opens your room and the gym, not other rooms | The token has limited scopes |
| The card stops working at checkout | The token expires |
| A door reads the card without phoning reception | An API can verify a token without calling the login server |
A lost key card is a problem, but a limited one: it opens only certain doors and only until checkout. A lost passport is far worse. Tokens exist so that the valuable thing, the password, is used as rarely as possible.
Why access tokens are short-lived
Because a stolen access token works for anyone, the main protection is time. If a token is valid for ten minutes, a thief has at most ten minutes.
Access tokens therefore usually live for minutes, not days. But that creates a new problem: nobody wants to type their password every ten minutes. The refresh token solves it.
What a refresh token is
A refresh token is a second, longer-lived token with exactly one job: getting a new access token.
| Access token | Refresh token | |
|---|---|---|
| Purpose | Call the API | Get a new access token |
| Sent to | The API, on every request | The login server only, occasionally |
| Typical lifetime | Minutes | Hours to weeks |
| If stolen | Usable until it expires | Can mint new access tokens, so it needs stronger protection |
Splitting the job in two means the token that travels constantly is the one that expires quickly, and the long-lived one is rarely sent and only to one place.
The full flow
Here is what happens from sign-in onwards.
- Sign in. The user proves who they are to the login server, which in OAuth is called the authorization server.
- Tokens issued. The app receives an access token and a refresh token.
- Call the API. The app sends the access token in the
Authorizationheader. - The token expires. The API answers
401 Unauthorized. - Refresh. The app sends the refresh token to the login server and gets a new access token, often with a new refresh token too.
- Retry. The app repeats the request with the new access token. The user notices nothing.
- Sign out. The app asks the server to revoke the refresh token, then forgets both tokens.
async function callApi(url) {
let response = await fetch(url, {
headers: { Authorization: `Bearer ${accessToken}` },
});
if (response.status === 401) {
accessToken = await refreshAccessToken(); // step 5
response = await fetch(url, {
headers: { Authorization: `Bearer ${accessToken}` },
});
}
return response;
}When the refresh token itself expires or is revoked, the refresh fails and the user signs in again.
Opaque tokens and JWTs
There are two common formats for an access token.
An opaque token is a random string with no meaning of its own, for example 8f3b1c9e.... The API looks it up, in a database or by asking the login server, to find out who it belongs to.
A JWT (JSON Web Token) carries the information inside itself, with a signature that proves it has not been changed.
| Opaque token | JWT | |
|---|---|---|
| Contents | Nothing readable | User ID, expiry, scopes |
| How the API checks it | Looks it up | Verifies the signature locally |
| Cancel it early | Easy: delete the record | Hard: it stays valid until it expires |
| Cost per request | A lookup | No lookup |
Neither is "more secure". A JWT saves a lookup, which helps when many services need to check tokens. An opaque token is easier to cancel. Many systems use a short-lived JWT as the access token and an opaque refresh token, which gets the benefits of both.
What is inside a JWT
A JWT is three parts separated by dots:
header.payload.signatureEach part is base64url-encoded. Decoded, the first two are plain JSON:
{ "alg": "RS256", "typ": "JWT" }{
"iss": "https://login.example.com",
"sub": "user_1842",
"aud": "https://api.example.com",
"exp": 1794567890,
"iat": 1794567290,
"scope": "messages:read"
}| Claim | Meaning |
|---|---|
iss |
Issuer: who created the token |
sub |
Subject: who the token is about, usually a user ID |
aud |
Audience: which API the token is meant for |
exp |
Expiry time, in seconds since 1970 |
iat |
When it was issued |
scope |
What the token is allowed to do |
The third part is the signature. The login server calculates it from the header and payload using a private key. Change a single character of the payload and the signature no longer matches.
A JWT is signed, not secret
This is the most common misunderstanding. Base64url is an encoding, not encryption. Anyone who has a JWT can read everything in it.
- The signature guarantees the contents were not changed.
- It does nothing to stop the contents being read.
So never put a password, a card number or anything private in a JWT payload. Put in only what the API needs to make its decision.
What the server must check
A token is only as trustworthy as the checks made on it. For every request, the API should:
- Verify the signature, using the login server's public key.
- Insist on the algorithm it expects. The header says which algorithm was used, but that header is written by whoever sent the token. Accepting whatever it says, including the value
none, is a classic vulnerability. Configure the allowed algorithm on the server. - Check
exp, and reject expired tokens. - Check
iss: the token came from your login server. - Check
aud: the token was issued for this API. Without this, a token issued for one service can be replayed against another. - Check the scope covers the action being requested.
Use a well-maintained JWT library for all of this and give it the expected algorithm, issuer and audience explicitly. Do not decode the token by hand and trust what you find: decoding is not verifying.
import { jwtVerify } from "jose";
const { payload } = await jwtVerify(token, publicKey, {
algorithms: ["RS256"],
issuer: "https://login.example.com",
audience: "https://api.example.com",
});
// Reaching this line means the signature, expiry, issuer and audience all passed.Common misunderstandings
- "A token is safer than a session cookie." Not by itself. Both are secrets that prove who you are. What matters is where it is stored and how long it lives.
- "JWTs are encrypted." No. The standard kind is only signed.
- "Logging out deletes the token." It deletes your copy. Unless the server revokes it, a stolen copy of a JWT keeps working until it expires. This is another reason to keep lifetimes short.
- "A long expiry is more convenient." A refresh token gives the same convenience without a long-lived access token.
Summary
- An access token proves a request is allowed. Whoever holds it can use it.
- It is short-lived, so a stolen one is useful only briefly.
- A refresh token quietly gets new access tokens, so the user stays signed in.
- A JWT carries readable, signed information. An opaque token is a random string the server looks up.
- A server must verify the signature, algorithm, expiry, issuer, audience and scope before trusting a token.
Knowing how tokens work is half of it. The other half is handling them safely in a real application: access token best practices covers where to store them, how long they should live and what to do when one leaks.
Further reading
- RFC 7519: JSON Web Token: the JWT specification.
- RFC 8725: JSON Web Token Best Current Practices: known pitfalls and how to avoid them.
- RFC 6750: Bearer Token Usage: how bearer tokens are sent.