JWT in Practice: How Authentication Tokens Work in APIs

The Authentication Problem in Modern Systems

Imagine working at the front desk of a large corporate office building. Every day, hundreds of people arrive wanting to enter. If every single door a visitor wanted to open required them to call the central administration to confirm their identity, the whole system would grind to a halt due to call overload. This is precisely the problem we face when building APIs, which are the contact points where client apps talk to servers.

In the past, servers kept a list of logged-in users in main memory or a central database. When a user made a request, the server had to query this list to check permissions. The problem is that as your application grows to handle thousands or millions of concurrent accesses, querying the database on every single click introduces latency and high infrastructure costs.

To solve this scaling bottleneck, software engineering adopted stateless authentication. In practice, this means the server no longer remembers that you logged in. Instead, it hands your app a self-explanatory digital pass upon initial entry. On subsequent requests, you present this pass, and the server simply checks its validity without needing to ask anyone else.

Anatomy of a JSON Web Token: What Lies Behind the Format

The most widely used standard format for this digital pass is the JSON Web Token, known as JWT. Technically, a JWT is nothing more than a long sequence of alphanumeric characters divided into three distinct parts, separated by dots. Each part plays a vital role in ensuring the identification is reliable, readable, and impossible to forge along the way.

The first part is the header, which specifies which cryptographic algorithm was used to sign the document, much like a wax seal on an old letter. The second part is the payload, home to useful user data such as internal IDs, email addresses, access permissions, and the exact token expiration date.

The third and most crucial part is the signature, mathematically generated by combining the header, payload, and a secret key stored securely only on the server. If anyone with malicious intent tries to alter even a single character of the email or permissions in transit, the mathematical signature instantly fails, exposing the fraud.

// Illustrative example of a decoded JWT payload
{
  "sub": "1234567890",
  "name": "Marcio Cunha",
  "email": "[email protected]",
  "roles": ["admin", "developer"],
  "exp": 1735689600
}

The Lifecycle: From Generation to Validation in the API

The practical flow of using a JWT starts when you fill out your email and password on a login screen and submit it to the API. The server receives these details, validates the credentials against the database, and if valid, uses its internal secret key to sign and generate the token. This token is returned as a response to the client application, which typically stores it locally.

From that moment on, whenever the app needs to fetch protected data — like your user profile or purchase history — it sends the token back inside the HTTP request header using a standard known as Bearer Token. In practice, the request header travels with text like Authorization: Bearer eyJhbGciOi....

On the server side, the API intercepts the request before it reaches business logic. It takes the received token, re-applies the mathematical function using the secret key, and compares the result with the signature at the end of the token. If the values match, the API trusts the payload data and grants access instantly, without opening any database connection.

Security in Practice: Storage and Common Pitfalls

One of the most severe and common mistakes when implementing JWTs is deciding where to store them on the client side, especially in web applications running in browsers. Many beginner developers save the token in the browser's local storage, known as LocalStorage. In practice, this is dangerous because any malicious script injected by a browser extension or third-party vulnerability can easily read this value and hijack the user session.

The recommended alternative for high-security web applications is storing the token inside a cookie with strict protection attributes such as HttpOnly and Secure. The HttpOnly attribute prevents JavaScript code from accessing the cookie, blocking data theft attacks, while Secure ensures the cookie only travels over encrypted HTTPS connections.

Another critical point is the expiration time. Because the server is stateless, once a valid JWT is issued, it remains valid until reaching the expiration date programmed in the payload, even if the user clicks logout or their permissions are revoked. Therefore, the best architectural practice is combining short expiration times with update tokens, commonly known as refresh tokens.

Final Considerations on Architecture and Scalability

The adoption of JSON Web Tokens has transformed how we design modern microservices architectures, allowing dozens of independent servers to validate identities without relying on a centralized database. However, this operational ease requires maturity in system design, demanding tradeoffs in revocation complexity and rigorous cryptographic key management.

Ultimately, a JWT is not a silver bullet that solves every security problem in an application, but rather an extremely powerful tool when applied within its ideal scope. Understanding its internal mechanisms and inherent vulnerabilities empowers engineers to build fast, highly scalable APIs secured against the most common threats in contemporary web development.