Access Tokens vs Refresh Tokens

Two tokens, two jobs

An access token is the credential a client presents on each and every API request. It is intentionally short-lived — often a matter of minutes — so that a leaked token has only a brief window in which it is useful to an attacker. A refresh token, by contrast, is longer-lived and is used solely to obtain fresh access tokens when the current one expires.

Keeping these two jobs separate is what lets you have frequent, low-risk access tokens backed by a single, more carefully guarded refresh token. The access token is handled constantly and held briefly; the refresh token is handled rarely and held securely. The Merion API follows this conventional split, and understanding why each token exists makes the rest of token handling far less mysterious when you build against it.

Why access tokens expire quickly

Short lifetimes exist to limit damage. If an access token is intercepted in transit or pulled from a log, it stops working soon afterwards, sharply reducing the value of the theft. There is also a performance dividend: because access tokens are typically self-contained, the resource server can validate one by checking its signature and claims, without a database lookup on every request.

The trade-off is that clients must renew tokens regularly rather than holding one indefinitely. That renewal is exactly what the refresh token automates, so users are not prompted to sign in again every few minutes simply because their access token lapsed. The result is security that is mostly invisible to the person using the application. We cover the mechanics and timing in Token Expiry and Renewal.

Using a refresh token

When an access token expires, the client sends its refresh token to the token endpoint and receives a new access token in return — and, with many providers, a new refresh token as well. This typically happens silently in the background, preserving the user's session without ever bouncing them back to a login screen.

POST /token
grant_type=refresh_token
&refresh_token=...

Many providers rotate refresh tokens on each use, issuing a fresh one and invalidating the previous token so that reuse of a retired token signals possible theft. Because of rotation, your client must always store the latest refresh token it receives and discard the old one, or the next renewal will fail. Treating refresh tokens as mutable, single-use-then-replaced values is the safe mental model.

Handling each safely

Because refresh tokens are long-lived, they are the more valuable target of the two and demand correspondingly stronger protection: encrypted storage, never exposed to front-end JavaScript, and revoked the moment a session ends or a user logs out. Access tokens, being short-lived, are usually held only transiently in memory while a request is made, then discarded.

Never store either token in a plain, world-readable file or anywhere it might be logged. For browser-based applications especially, prefer secure server-side handling of refresh tokens over leaving them in local storage, where any injected script could read them. The asymmetry is the key idea: protect the refresh token as you would a password, and treat each access token as disposable. Get those two instincts right and most token-handling pitfalls simply do not arise.