DEV Community: Charity Atieno

What Are JWT Tokens and How Do They Work? A Beginner-Friendly Guide

Charity Atieno — Mon, 23 Mar 2026 07:16:12 +0000

Posted as part of my build-in-public series on Kaya, a verified house-hunting platform I am building for the Kenyan market.

If you have ever logged into a website and stayed logged in as you moved from page to page, something behind the scenes was keeping track of who you are. One of the most common ways modern backends handle this is with JWT tokens. When I started building the authentication system for Kaya, JWTs were one of the first things I had to truly understand, not just use from a tutorial, but actually get. This article is my attempt to explain them the way I wish someone had explained them to me.
The Problem JWTs Solve
Before JWTs, the most common approach to authentication was sessions. Think of it like a coat check at a restaurant. You hand over your coat, the attendant gives you a ticket with a number on it, and every time you want your coat back you show the ticket and they look up your coat in the back room. Simple enough when there are ten people. But what happens when there are ten thousand? The back room gets crowded, the lookups get slower, and the whole system starts to strain.

That is exactly what happens with session-based authentication at scale. You log in, the server creates a session record in a database, and sends you a session ID as a cookie. Every single request you make sends that session ID back, and the server has to look it up in the database every single time. As your application grows, this puts real pressure on your infrastructure.
JWTs offer a completely different approach, one where the server does not need to store anything at all.

So What Is a JWT?
JWT stands for JSON Web Token. Instead of the coat check giving you a ticket and keeping your coat in a back room, imagine they stamped all your details directly onto a card, sealed it with wax, and gave it back to you. Now whenever you show up, they just read the card and check the seal. No back room. No lookups. If the seal is intact, you are good.

That is a JWT. It is a compact, self-contained string that carries the user's information and a cryptographic signature to prove it has not been tampered with. A JWT looks something like this:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyX2lkIjoiYWJjLTEyMyIsImV4cCI6MTcwMDAwMDAwMH0.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

Looks like chaos, right? It is actually three parts separated by dots: the header, the payload, and the signature. Let us break each one down.
Part One: The Header
The header is the least exciting part. It simply tells the server what type of token this is and which algorithm was used to sign it.

{
  "alg": "HS256",
  "typ": "JWT"
}

HS256 stands for HMAC with SHA-256, a secure and widely used signing algorithm. This object is then Base64URL encoded to produce the first chunk of the token. Nothing secret here, just metadata.

Part Two: The Payload
This is where the actual information lives. The payload contains what are called claims, which are just key-value pairs describing the user or the token itself.

{
  "user_id": "abc-123",
  "phone": "254712345678",
  "exp": 1700000000
}

Some common claims you will encounter are sub, which is the subject and usually holds the user's ID, exp which is the expiry timestamp telling the server when this token stops being valid, and iat which is the issued-at time recording when the token was created.

Here is the part that trips a lot of beginners up: the payload is encoded, not encrypted. That means anyone who gets hold of a JWT can decode it and read everything inside. Go ahead and paste any JWT into jwt.io and you will see exactly what I mean. So the golden rule is this: never put sensitive information like passwords or secret keys inside a JWT payload.

Part Three: The Signature
This is where the trust lives. The signature is created by taking the encoded header and payload, combining them, and running them through a hashing algorithm using a secret key that only your server knows.

HMACSHA256(
  base64UrlEncode(header) + "." + base64UrlEncode(payload),
  your-secret-key
)

Think of the signature as the wax seal on that card from our earlier analogy. When someone presents a token, your server re-runs this calculation using its secret key. If the signature matches, the token is genuine. If someone has tampered with the payload, even by changing one single character, the signature will not match and the server will reject the token immediately.

This is the elegant part of JWTs: the server can verify who you are without asking anyone or looking anything up. The token proves itself.

How the Full Flow Works

Let us walk through what actually happens when a user logs in to an app that uses JWTs.

User sends credentials to the server
         |
Server verifies the credentials
         |
Server creates a JWT with the user's ID and expiry,
signs it with the secret key, and sends it back
         |
User stores the token (in memory or localStorage)
         |
For every future request, the user sends:
Authorization: Bearer <token>
         |
Server reads the token, verifies the signature,
checks the expiry, knows who you are.
No database. No session lookup. Done.

You will notice the word Bearer before the token. It is just a convention that tells the server what kind of credential is being sent. It means "the person presenting this token should be granted access." Nothing more to it than that.

Why Tokens Cannot Live Forever
Every JWT should have an expiry time. In the Kaya backend I set it to 24 hours. Here is why this matters: unlike sessions, a JWT cannot be invalidated by the server once it has been issued. If someone gets hold of your token, they can use it freely until it expires. Setting a short expiry limits the damage window if a token is ever compromised.

This leads to one of the core trade-offs of JWTs. They are fast, stateless, and scale beautifully because the server stores nothing. But they are also difficult to revoke. If you need to log a user out immediately, for example if their account is suspended, you have to build additional mechanisms on top of the basic JWT approach to handle that. For most applications though, a sensible expiry time is enough.

How This Fits Into Kaya
In the Kaya backend, JWTs sit at the heart of the authentication system. When a user successfully verifies their identity, the server creates a JWT containing their unique ID, signs it with a secret key stored securely in the environment, and returns it to the client. From that point on, every request to a protected route must include that token. A middleware function intercepts each request, validates the token, and either allows it through or returns a 401 Unauthorized response.
The result is a backend that never stores login state. Every request is self-contained and verified on the spot. For a platform like Kaya where access to certain listing details is gated behind verified identity and payment, having a reliable and stateless authentication layer is not optional; it is foundational.

Key Takeaways

A JWT is made of three parts: the header, the payload, and the signature
The signature is what makes it trustworthy and proves nothing has been tampered with
The payload is readable by anyone, so sensitive data should never go inside it
Tokens should always have an expiry time to limit damage if one is ever compromised
The server verifies everything using a secret key with no database lookup required
JWTs are stateless, fast, and scale well but they cannot be invalidated once issued without additional mechanisms

Growing as a developer through open source contribution

Charity Atieno — Tue, 24 Feb 2026 12:21:23 +0000

Open source contribution is often described as a milestone in a developer’s journey. After recently contributing to a Go open source project, I now understand why.

It is one thing to build personal projects where you control the structure, naming, and decisions. It is another thing entirely to step into a living codebase maintained by people across different time zones, skill levels, and perspectives. Open source forces you to grow in ways tutorials cannot.

Many of us use open source tools daily. Frameworks, libraries, and developer tools quietly power our applications. Contributing shifts your mindset from being just a user to becoming a collaborator. Instead of asking how to use a tool, you begin asking how it works internally and how to improve it without disrupting existing behavior. That shift deepens your technical understanding significantly.

One of the biggest lessons for me was learning to read and understand someone else’s code at scale. In open source, you cannot refactor everything to match your personal style. You must understand the existing architecture, follow established conventions, respect maintainers’ decisions, and ensure your changes align with the project’s direction. This builds discipline and strengthens your ability to work within constraints, just like in professional engineering teams.

Open source is not just about writing code. It is about communication. You discuss ideas through issues, submit changes through pull requests, receive feedback, and revise your work when necessary. The focus is not on proving yourself right. The focus is on improving the project. This process builds humility, resilience, and clarity in how you explain technical decisions.

Contributing also changes how you think about quality. You become more intentional about writing clean and readable code, considering edge cases, maintaining compatibility, and ensuring proper testing. In personal projects, speed often comes first. In open source, responsibility comes first because other developers rely on the code you contribute.

For me, contributing to a Go open source project strengthened both my technical foundation and my confidence. It reminded me that real growth happens when you step into unfamiliar spaces and build in public.

Understanding APIs Through Errors JSON and Status Codes

Charity Atieno — Fri, 13 Feb 2026 10:16:24 +0000

I used to joke that APIs are like introverts at a party: you never know if they’ll respond or ignore you entirely. When I first started learning about them, I felt exactly like that completely in the dark.

Over time, I’ve gradually improved. I’ve learned how GET and POST requests work, how to handle errors in JSON, and why sending the correct HTTP status codes matters. These may seem small, but they make your API predictable, professional, and friendly for anyone consuming it.

Here are a few key lessons I’ve learned:

GET vs POST: GET retrieves data, POST sends data. Using them correctly is the foundation of any API.

Error Handling: Clear error messages in JSON help clients understand what went wrong and how to fix it.

Status Codes Matter: Using the right HTTP status code communicates the result of a request without needing to dig into the response body. Examples:

200 OK – request succeeded

400 Bad Request – client sent invalid data

401 Unauthorized – authentication required or failed

Here’s a small Go example I built that takes a user’s name and returns a personalized greeting:


package main

import (
    "encoding/json"
    "net/http"
)

type User struct {
    Name string `json:"name"`
}

func greetHandler(w http.ResponseWriter, r *http.Request) {
    if r.Method != http.MethodPost {
        w.WriteHeader(http.StatusMethodNotAllowed)
        return
    }

    var user User
    decoder := json.NewDecoder(r.Body)
    if err := decoder.Decode(&user); err != nil {
        w.WriteHeader(http.StatusBadRequest)
        json.NewEncoder(w).Encode(map[string]string{"error": "Invalid JSON"})
        return
    }

    w.WriteHeader(http.StatusOK)
    json.NewEncoder(w).Encode(map[string]string{"message": "Hello " + user.Name})
}

func main() {
    http.HandleFunc("/greet", greetHandler)
    http.ListenAndServe(":8080", nil)
}

Testing the API

Once the server is running, you can test it easily:

Using curl:

curl -X POST http://localhost:8080/greet \
-H "Content-Type: application/json" \
-d '{"name":"Charity"}'

You should see:

{"message":"Hello Charity"}

Using Postman:

Open Postman and create a new POST request.

Set the URL to http://localhost:8080/greet.

In the body, select raw JSON and enter:

{"name":"Charity"}

Send the request and you’ll see the greeting returned.

Even this simple example reinforces why proper JSON formatting, error handling, and status codes are essential. Small improvements like these make APIs much easier to use and understand, and they transform something that once seemed intimidating into a tool I can confidently build with.

APIs may have seemed introverted at first, but once you speak their language, they’re actually pretty friendly.