DEV Community: Amorto Goon

A Guide to Refresh Tokens: The Bare Minimum for Auth Security

Amorto Goon — Sat, 15 Aug 2026 16:33:36 +0000

What motivated me to write this

I was looking for good authentication tutorials when I was just starting with web development. Back then I didn't know any better. I came across a video on youtube and thought to myself, "WOW! It's that easy?"

Most of the videos I came across back then had a lot of flaws, some were using refresh token only to refresh access tokens automatically without doing anything else, while others were completely missing the point of refresh token.

This tutorial will not make you the master of authentication but after reading this, I'm hoping you'll understand the bare minimum that you need to implement a secure auth system for your web app. I'm also hoping to learn something new, and fix my own bad habits and mistake if you point it out.

Before we start

This is going to be a general guide and not a programming language specific tutorial. However, to show coding snippets and example, I will be using Typescript as it is a popular language among web devs.

In this article, we will take a look at basic auth flow, what tokens are and the use for a refresh token.

In the next article in this series, I will show code snippets and how to actually implement this.

The basic auth flow

When we visit a website and log into our account, we usually provide our email and password once. After that we can close the tab and even browser, but still are logged in. It'd be a hassle to log in every time we close the tab. This is why we use tokens. Once a user logs in, we send over a token from the server. After that for each request, the client/browser sends over the token and using that token we verify who the user is.

Generally when we log in, the server verifies that the email and password is correct. Then the server generates a token and send it to the client. This is how the authentication flow looks like assuming the log in was successful.

When the login is successful, the server sends a set of token (usually two) or session id as cookie. From there, every request will send that cookie to verify who the user is. The flow looks like this assuming the token is not expired and is correct.

Password Hashing

Repeat this with me, "Never store raw password in a database". Password is the key to our digital life and databases are not a secure home where no one can break in and steal that key.

To avoid our users password getting leaked, we use a one way encryption known as password hashing.

When user provides password to sign up, we hash the password and store it in our database.

When user provides password to sign in, we use the password hashing algorithm's verification function to check whether the provided password matches with the hashed password.

What is a token

In simple words, tokens in authentication are credentials that the server generates. To us, they might look like a randomized string.

It has a payload that contains information that is required for secure authorization. We use these information to authorize the user to different resources.

These tokens are cryptographically signed with a key. When the time comes for our server to verify the token, it verifies the signature to check if the token is valid and hasn't been tampered with.

Json Web Tokens or JWT are commonly used for authentication. We store payload, that is user id for example and we set a time when the token will be expired.

Why tokens should be short-lived

Unlike traditional session based authentication, tokens can be verified without storing each of them in the database.

If an attacker steals our token from a user, the attacker can pretend to be the user and use our services.

We could store compromised tokens in our database, but hitting the database each time a request arrives to check if this token is compromised defeats the whole purpose of using a JWT in the first place.

Short expiry time is a UX killer

If your favorite app asks you to log in every 15 minutes, how would you feel?

A shorter expiry time means our users need to log in every time the token is expired, to get a new one. To solve this issue, we can give our users two tokens, one will have aa expiry of 15 minutes and another will have a longer lifespan, like 14 days or even 30 days.

When the short-lived token, A.K.A the access token expires, we can generate a new pair of token and set them as cookie.

When we fresh the access token, we can store the token that was used to generate a new set somewhere (usually database). That way when a user tries to reuse an old token, we know that the token is stolen and we can immediately take action.

Because we use the 2nd token to refresh the token pair. It is called Refresh Token.

Refresh token

This is where most people mess up. The purpose of refresh tokens is to make sure our access token is short lived. That way if the tokens are stolen, we can minimize the damage.

In most tutorials I've seen people just generating new tokens with refresh token when access token is expired. Some check if the user still exists in the database, and others are confused and only generate new set of tokens without verifying anything.

That defeats the purpose.

Ideally, when a refresh token is used, we should check if this token was already used before to generate a new set of tokens.
Reuse of a used token is suspicious and it is better that we invalidate the entire token family as a security response.

We do not know who stole the token, but we know that the token is probably stolen. In that case, we should revoke the entire refresh token family.

We can mark each of our refresh tokens by a familyId or something else. This information should be stored in a database to identify tokens that belong to the same token family.

When a user logs in for the first time, we can create a familyId and attach it as payload to our refresh token.

When access token is expired and a new token is needed, we can extract and attach the same familyId to the new refresh token.

Of course a jti or token id should be stored in the database along with familyId in the database. The schema should at least contain these information,

userId - [id of the user]
familyId - [id that is attached to each refresh token]
usedAt - [timestamp when this refresh token was used, default NULL]
revokedAt - [when the refresh token was revoked, default NULL]
expiresAt - [when the token naturally expires]
jti - [primary key, unique for each refresh token]

When a token is compromised, we should invalidate all the tokens with same family id.

When user chooses an action to "Log out from everywhere", we should invalidate all the refresh tokens from our database containing the id of that user.

Conclusion

To put everything together.

When a user signs up for the very first time, we hash the password and store it. NEVER STORE PLAIN PASSWORDS TO DATABASE.

After successful login, we send two tokens to the user. Access Token and Refresh Token. Access tokens have shorter lifespan while refresh tokens have relatively longer lifespan.

When access token is expired, use refresh token to generate a new access token. Prevent refresh token reuse.

If we understand this much, we already have a good foundation to implement an authentication system.

Of course there are many security concerns like Cookie security, CSRF protection, XSS etc but we cannot cover all of them in one article.

The goal of the article is to understand why access tokens are short lived, the need for refresh tokens and a proper way to handle them together.

In the next part, we will take a look at how to implement this.

If you read it this far, thank you. Let me know what you think or if you know a better way this can be done.

Go + Echo: The Simple Way to Build a Web Server

Amorto Goon — Sun, 22 Mar 2026 14:14:51 +0000

Building a performant API shouldn't feel like a chore. If you're looking for a simple language that is fun and performant, look no further than go. There are a lot of frameworks for GO but today we will be choosing Echo.

TLDR

Project Setup: Initializing a Go module
Echo Basic: Creating echo instance for route handling with v5
Routing: Handling Get Request

Before we begin

In this guide, we will not go over how to install and setup go. It's assumed you already have go installed and configured.

We are also assuming you know basic Go syntax and how to create a simple hello word program.

1. Project setup

To start, we need to initialize a go module in our current working directory. Once you are in a folder where you'd like to build this application, initialize module.

go mod init myserver

Ideally, you'd put your source code location, for example github.com/[your_username]/[repo_name] but for the sake of simplicity we will be using myserver instead.

2. Echo Basic

To use Echo as our framework, we need to create a main package first.

Step 1. Create a file and name it main.go. We can also run the following command to create the file. Make sure we are still on our working directory.

touch main.go

Step 2. Inside main file let's create a simple main function and print hello world.

package main

import "fmt"

func main() {
    fmt.Println("Hello World!")
}

Now we can run our application and see Hello World! printed on our terminal.

To run this application,

go run main.go

Step 3. Now that we have a basic working application, we can bring in Echo to create our server.

To install Echo,

go get github.com/labstack/echo/v5

Step 4. After installing Echo successfully we can start creating our API.

After this guide, we want to visit http://localhost:4000/hello and get a json response similar to this.

{
    "message": "Hello World!"
}

To achieve our goal, let's start adding changes to our main.go file.

//main.go

package main

import (
    "net/http" // import net/http for HTTP status codes

    "github.com/labstack/echo/v5" //import echo v5
)

func main() {
    // Create a new Echo instance
    e := echo.New()

    // Define a route for GET requests to "/hello"
    e.GET("/hello", func(c *echo.Context) error {
        return c.JSON(http.StatusOK, map[string]string{
            "message": "Hello World!",
        })
    })

    // Start the server on port 4000 and log any errors that occur
    if err := e.Start(":4000"); err != nil {
        e.Logger.Error("failed to start server", "error", err)
    }
}

We have made quite a bit of changes here. I have made to sure to add comments so we can understand what each chunk of code does even before you get to this line. However, let's a still dive a bit deeper.

Initializing Echo: Before we can use any of the functionality that echo provides us, we have to initialize it. We can do so by using echo.New() and importing the echo package github.com/labstack/echo/v5.
Get request: In Echo, if we want to create an endpoint we can do so by using the variable where we stored our echo instance. Similarly we can also use e.POST(), e.PUT(), e.DELETE() etc.
Returning JSON: To make our endpoint return a json response we have to use c.JSON(). It accepts two parameters, one is the http status code. You might have noticed that we are using go http package to return the status code, you can also use 200 instead of using http.StatusOK. The other parameter is our response data. To return a JSON response, we are using map. We can return all sorts of data through the second parameter.
Logging: Things can go south anytime, that's why we are making sure we are printing any errors that may occur, making things easy for debugging in future.
Starting the server: To Start the server, we used e.Start(). Since we were planning to start our server on port 4000. We can pass :4000 through e.Start() parameter.

Just like that, we now understand how to build an Echo server and a simple explanation of all the functions we used.

But we are not done yet..

Step 5: Now we have to test our API.

Run our go application using,

go run main.go

If the application is running successfully, open your browser and visit http://localhost:4000/hello.

We should see json response saying hello to the entire world.

And that's it. You have successfully initialized a go module, initialized echo and created a basic performant custom api endpoint.

Thank you everyone for reading! This is my first article on dev.to. I'd love to hear your feedback, or any tips you have for a new writer. Happy coding!