JSON Web Token Structure and How Signed Claims Protect APIs

A JSON Web Token (JWT) is a compact, URL-safe data format that transmits verifiable statements between network services. Standardized under RFC 7519 (ISSN: 2070-1721) by Michael B. Jones from Microsoft, John Bradley from Ping Identity, and Nat Sakimura from NRI under the Internet Engineering Task Force (IETF) and approved by the Internet Engineering Steering Group (IESG), the open standard packages user identity details and session metadata inside a signed JSON object. The specification builds on JSON Web Signature (JWS) and JSON Web Encryption (JWE) under RFC 5741 guidelines and BCP 78 legal provisions [1]. Rather than storing session state across multiple backend database tables, distributed architectures rely on these tokens to pass identity claims directly to protected API endpoints. The format relies on digital signatures to protect payload contents from client-side tampering, letting receiving servers verify authenticity without repetitive database lookups [2].

The Three-Part Token Structure

Every token consists of three distinct segments separated by periods, appearing in compact transmission as header, payload, and signature [2]. Developers convert the underlying JSON data using Base64URL encoding under RFC 4648, which strips padding equals signs and replaces standard base64 characters to stay safe inside web URLs and HTTP query parameters [9]. The three parts string together into a single lightweight text sequence [2].

The token header specifies the metadata needed to process incoming claims, declaring the token type typ and the signing algorithm alg [1]. Common algorithm values include HS256 for symmetric shared keys and RS256 for asymmetric public key pairs [9]. To build the signature, the issuing service takes the encoded header, appends a period, adds the encoded payload, and hashes the concatenated string using the chosen algorithm and a private secret. If an attacker alters a single character in the payload, the computed signature no longer matches, and the server rejects the request [2].

Interactive developer platforms like jwt.io from Auth0 provide online debuggers where developers can paste encoded strings to view the plain JSON header and payload in real time. The tool paints the header in red, the payload in magenta, and the signature in cyan, showing how Base64URL string decoding exposes raw claims. This transparency shows a basic security rule: signed tokens guarantee data integrity, but they do not hide payload contents from anyone who intercepts network traffic. Because the segments rely on basic string encoding rather than encryption, anyone who inspects an unencrypted token can read its claims right away. Sensitive user records like raw passwords, private keys, or bank details must never sit inside an unencrypted JSON Web Token payload [2].

Registered Claims in the Token Payload

RFC 7519 establishes seven registered claim names designed to provide a standard vocabulary across web apps. These registered claims include iss for the issuer identity, sub for the subject identifier, aud for the intended audience, and jti as a unique token identifier to stop replay attacks. The specification deliberately keeps these keys three letters long so the serialized string consumes minimal bandwidth over network connections [1].

Temporal claims define the valid lifespan of a token, relying on timestamps formatted as seconds elapsed since the Unix epoch on January 1, 1970 UTC [5]. The exp claim sets the exact second after which receiving services must reject the token, preventing expired credentials from gaining unauthorized access. Conversely, the nbf claim specifies the moment before which the token is not yet valid, while the iat claim records when the issuer created the token [1]. Tools like Jwt.Net allow administrators to configure clock-skew margins, accommodating minor time differences between distributed server clocks [5].

Beyond registered fields, apps rely on public and private claims to transmit custom user data [1]. Public claims can be chosen freely by developers, but they should be registered in the IANA JSON Web Token Claims Registry or defined with collision-resistant URIs to prevent naming conflicts across independent services. The IANA registry tracks standardized attributes like email, roles, and OpenID Connect parameters [4]. Private claims represent custom key-value pairs agreed upon between cooperating parties, such as adding a tenant identifier or administrative flag directly into the user payload [2]. While none of these predefined fields are mandatory, standards recommend including issuer and audience checks whenever tokens cross system boundaries, so receiving servers only process claims intended for their specific service [1].

How JSON Web Token Authentication Operates

During typical user authentication, a client submits credentials to an identity server, which validates the password and returns an encoded token [2]. The client app preserves this token and attaches it to subsequent network calls, placing the value inside the standard HTTP Authorization header using the Bearer schema [9]. A standard header entry reads Authorization: Bearer token, transmitting the serialized string with each API call. By avoiding traditional session cookies in browser requests, mobile apps and single-page apps easily bypass common Cross-Origin Resource Sharing restrictions [2].

API gateways check incoming requests in a stateless manner by checking the signature against the server public key or shared secret. Because the token self-contains user permissions and identity claims, backend microservices handle authorization decisions without querying a central database for every single HTTP request. This architectural setup simplifies Single Sign-On across multiple domains, where different web services accept tokens signed by a shared auth authority [2].

Server systems often set fixed memory limits on incoming HTTP request headers, with many web servers rejecting requests whose headers exceed 8 KB. Embedding hundreds of nested user permissions inside a single payload inflates the token size and causes web servers to reject large headers. While web applications execute client-side logic using WebAssembly bytecode, token verification typically occurs at backend API gateways. Architects who need extensive authorization models often store minimal user identifiers in the token and look up granular access policies through specialized permission engines [2]. If thousands of users access a cluster at the same time, this hybrid design keeps header sizes compact while avoiding database connection bottlenecks across distributed microservices [11].

Why We Use JSON Web Token Standards

When compared to older mechanisms like Simple Web Tokens (SWT) and Security Assertion Markup Language (SAML), JSON offers clear efficiency gains for web apps. XML-based SAML assertions carry heavy structural overhead, generating bulky payloads that consume excessive bandwidth when passed through query parameters or HTTP headers [2]. In contrast, the compact syntax of JSON minimizes transmission size while remaining URL-safe across modern web setups [1].

Software development environments handle JSON structures natively because JSON maps directly to data objects in languages like JavaScript, Python, C#, and Go. XML parsers do not offer a natural document-to-object mapping, requiring complex schema validation tools that increase runtime processing costs. Simple Web Tokens supported only symmetric shared secrets through the HMAC algorithm, forcing every verifying service to hold the same secret key used to issue tokens. Modern tokens support both shared secrets and public key pairs, allowing services to verify signatures without holding signing keys [2].

Implementing XML Digital Signatures without introducing security holes has historically proven difficult for engineering teams. Canonicalization issues and complex XML parsing rules frequently led to auth bypass bugs in enterprise deployments [2]. In contrast, the JSON Web Signature specification outlined in RFC 7515 defines a streamlined approach where checking simply compares hashes over concatenated strings. This simplicity reduces parsing ambiguities, enabling consistent signature checks across diverse operating setups and programming languages [10]. Because mobile devices and modern browser clients operate over bandwidth-sensitive connections, the smaller footprint of a JSON Web Token makes network transport noticeably faster, establishing it as the standard mechanism for token-based authorization on the modern web [2].

Cryptographic Algorithms in JWS and JWE

The JSON Web Algorithms specification in RFC 7518 catalogs mathematical algorithms for signing and encryption [10]. Symmetric signing algorithms like HS256, HS384, and HS512 generate a Message Authentication Code using a secret key known to both issuer and validator [8]. Asymmetric algorithms allow issuers to sign claims with a private key while consumers verify them using a public key [1]. Supported suites include RSA algorithms and elliptic curves like ES256 [8].

When token claims contain confidential data, systems deploy JSON Web Encryption under RFC 7516 [8]. While a signed JWS token keeps claims readable to anyone who inspects the string, a JWE token encrypts the payload into ciphertext using a Content Encryption Key [1]. JWE compact serialization uses five segments separated by dots: header, encrypted key, initialization vector, ciphertext, and authentication tag. Algorithms such as A128GCM make sure that only parties holding the corresponding decryption key can read payload claims [8].

Empirical research shows measurable performance variations across different algorithm selections. In a 2023 evaluation of RESTful API session management, S. Dalimunthe, E. H. Putra, and M. A. F. Ridha compared HMAC-SHA512 with HMAC-SHA256, recording a total time difference of 185 ms and an average difference of 6.17 ms. Their benchmark revealed that HMAC-SHA512 operated 0.9861% faster than HMAC-SHA256 [14]. In 2022, N. Rasyada measured average request speeds of 512.8 ms for SHA-512 compared to 515.55 ms for SHA-256 [15]. In 2019, A. P. Aldya, A. Rahmatulloh, and M. N. Arifin found that RSA-512 processing on RESTful architectures was 24.69% faster than SOAP, with token auth proving 11.64% faster and generating payloads only 1.25% larger [13].

Implementation Libraries Across Ecosystems

System developers often integrate native tools to process tokens in resource-constrained environments. The open-source libjwt library in C supports both compact and general JSON serializations. The library operates with JSON parsers such as Jansson (version 2.0 or higher) and json-c (version 0.16 or higher), while pairing with crypto backends including OpenSSL, GnuTLS, and MbedTLS [6].

In functional programming ecosystems, Fraser Tweedale created the jose package on Hackage, implementing JSON Object Signing and Encryption standards for Haskell apps. The package provides complete support for RFC 7515 signatures, including modern Edwards-curve EdDSA signatures under RFC 8037 and secp256k1 keys under RFC 8812. Tweedale notes that while the tool fully validates signatures across diverse curve parameters, developers must use ECDSA routines solely for verification to avoid subtle timing attack flaws. The package provides verified type safety, preventing common memory corruption risks when parsing complex signed assertions [7].

Across dynamic and enterprise frameworks, mature packages handle token operations reliably. On MetaCPAN, Karel Miko maintains Crypt::JWT, a Perl module implementing RFC 7519 that supports both JWS and JWE across compact and flattened serializations. Miko warns developers to shape key arguments carefully, noting that passing public key strings as bare scalars allows attackers to execute algorithm confusion attacks [8]. Similarly, the Jwt.Net library provides extensive support for ASP.NET Core, .NET Framework 3.5 through 4.8, and .NET 6.0, offering dedicated builders to encode, decode, and validate custom claims. By implementing standard interfaces like IJwtAlgorithm and IJsonSerializer, developers can easily plug custom serialization routines directly into production auth pipelines [5].

Preventing Algorithm Confusion and Invalidation Flaws

In March 2015, security researcher Tim McLean published an analysis on Chosen Plaintext detailing severe flaws across multiple token implementations. McLean discovered that several tools blindly trusted the alg parameter in the token header to determine verification logic. Attackers could alter the header to specify alg: none, strip the signature, and submit forged administrator claims that vulnerable servers accepted as valid [3].

A more dangerous implementation flaw arises when servers accept asymmetric RSA tokens but allow algorithm switching to symmetric HMAC. In this scenario, an attacker downloads the server’s public RSA certificate, changes the token header to HS256, and signs the forged payload using the public key text as an HMAC shared secret. Because flawed verification functions check the signature against whatever key object was provided, the server uses its public key to verify the HMAC hash and accepts the forged token [3]. To stop this exploit, libraries like Crypt::JWT enforce algorithm pinning through parameters like accepted_alg, completely ignoring untrusted header assertions [8].

Revoking credentials before their scheduled expiration remains a persistent challenge in stateless authentication architectures. In a 2018 study published in the International Journal of Distributed Sensor Networks, L. V. Jánoky, J. Levendovszky, and P. Ekler examined token invalidation techniques, explaining that maintaining revocation lists reintroduces centralized database overhead and undermines scalability [12]. On client devices, storing tokens in browser local storage exposes credentials to untrusted client-side scripts. Security guidelines recommend storing credentials in HTTP-only cookies with the Secure flag enabled, preventing malicious browser scripts from extracting tokens. In addition, four separate CVE reports between 2018 and 2021 showed that algorithm confusion bugs still resurface when tools fail to separate public verification keys from private secrets [9].

What Is JSON Web Token Used for Next?

Modern identity specifications increasingly deploy JSON Web Token structures within specialized application profiles rather than inventing new cryptographic standards. RFC 9068 defines an explicit profile for OAuth 2.0 access tokens, using the at+jwt media type header to ensure tokens are not confused with OpenID Connect ID tokens. To defend against token theft, RFC 9449 introduces Proof-of-Possession (DPoP), binding tokens to a client’s private key via an ephemeral thumbprint [6].

The standardization of Entity Attestation Tokens under RFC 9711 extends token formats to hardware security modules and Internet of Things setups. The IANA registry defines specialized hardware claims including hwmodel, oemid, dbgstat, and boot verification flags that describe the physical integrity of a booting device. These attestation tokens allow remote cloud servers to confirm that an edge sensor or network gateway runs untampered firmware before granting network access. Combining hardware measurements with standard claims bridges enterprise identity systems with low-level embedded hardware security [4].

To protect future deployments from historical implementation errors, the IETF published Best Current Practices under RFC 8725, designated as BCP 225. The document instructs developers to validate token types explicitly, reject unexpected algorithms, and enforce tight clock margins. Modern web trust models rely on public key infrastructure, where systems distribute cryptographic trust through Merkle tree certificates and established certificate authorities. Under DPoP protocols, even if an attacker intercepts an in-transit token, they cannot present it to protected endpoints without possessing the matching private key [6]. By following standardized verification guidelines and selecting appropriate key management practices, development teams can build scalable architectures that keep user data secure [1].

1. ^REPORT Jones, M., Bradley, J., & Sakimura, N. (2015). JSON Web Token (JWT) (RFC 7519). Internet Engineering Task Force. [Article Link]
2. ^WEBSITE Auth0. (2024). Introduction to JSON Web Tokens. JSON Web Tokens – jwt.io. [Article Link]
3. ^WEBSITE McLean, T. (2015). Critical vulnerabilities in JSON Web Token libraries. Chosen Plaintext. [Article Link]
4. ^WEBSITE Internet Assigned Numbers Authority. (2010). JSON Web Token (JWT) claims registry. [Article Link]
5. ^WEBSITE Jwt.Net Contributors. (2011). Jwt.Net, a JWT implementation for.NET. GitHub. [Article Link]
6. ^WEBSITE Collins, B. M. (2015). LibJWT: The C JSON Web Token library. GitHub. [Article Link]
7. ^WEBSITE Tweedale, F. (2026). jose: JSON Object Signing and Encryption (JOSE) and JSON Web Token (JWT) library. Hackage. [Article Link]
8. ^WEBSITE Miko, K. (2026). Crypt::JWT – JSON Web Token (JWT, JWS, JWE) as defined by RFC7519, RFC7515, RFC7516. MetaCPAN. [Article Link]
9. ^WEBSITE Wikipedia Contributors. (2026). JSON Web Token. Wikipedia, The Free Encyclopedia. [Article Link]
10. ^WEBSITE Wikipedia Contributors. (2026). JSON Web Signature. Wikipedia, The Free Encyclopedia. [Article Link]
11. ^{ACADEMIC JOURNAL} Mahindrakar, P., & Pujeri, U. (2020). Insights of JSON Web Token. International Journal of Recent Technology and Engineering, 8(6), 1707–1710. [Article Link]
12. ^{ACADEMIC JOURNAL} Jánoky, L. V., Levendovszky, J., & Ekler, P. (2018). An analysis on the revoking mechanisms for JSON Web Tokens. International Journal of Distributed Sensor Networks, 14(9), 155014771880153. [Article Link]
13. ^{ACADEMIC JOURNAL} Aldya, A. P., Rahmatulloh, A., & Arifin, M. N. (2019). Stateless Authentication with JSON Web Tokens using RSA-512 Algorithm. Jurnal Infotel, 11(2), 36–36. [Article Link]
14. ^{ACADEMIC JOURNAL} Dalimunthe, S., Putra, E. H., & Ridha, M. A. F. (2023). Restful API Security Using JSON Web Token (JWT) With HMAC-Sha512 Algorithm in Session Management. IT Journal Research and Development, 8(1), 81–94. [Article Link]
15. ^{ACADEMIC JOURNAL} Rasyada, N. (2022). SHA-512 Algorithm on Json Web Token for Restful Web Service-Based Authentication. Journal of Applied Data Sciences, 3(1), 33–43. [Article Link]