What Is a JWT Token? Architecture, Structure, and Implementation Guide

A JSON Web Token (JWT) is an open industry standard defined by RFC 7519 for transmitting information and claims securely between two parties as a compact, URL-safe JSON object. In modern software architecture, it is primarily used as a stateless mechanism for authentication and authorization, enabling a client to present cryptographically verifiable credentials to a server without requiring server-side session storage.

Cryptographic Context: How Signing Versus Encryption Changes What a JWT Is

To understand what a JWT is in practical use, you must first distinguish between the two primary cryptographic contexts defined in the underlying standards: signed tokens and encrypted tokens.

In the OpenID and core specifications, a token represents claims that are encoded as a JSON object and either digitally signed using JSON Web Signature (JWS), encrypted using JSON Web Encryption (JWE), or both. The functional role of the token changes completely depending on which of these two approaches an architecture implements:

• Signed Tokens (JWS): This is the predominant context in web development. In a signed token, the payload data remains unencrypted. Anyone who intercepts or reads the token can decode the base64-encoded JSON text and view the payload claims. However, the cryptographic signature ensures data integrity. Because the signature is calculated across both the header and the payload using a shared secret or a cryptographic key pair, any alteration to the data invalidates the signature. Signed tokens verify that the contents have not been tampered with and certify the authenticity of the sender, but they do not provide confidentiality.
• Encrypted Tokens (JWE): In an encrypted context, the payload claims are encrypted so that third parties and untrusted transport layers cannot read the underlying JSON object. While signed tokens ensure integrity and non-repudiation, encrypted tokens provide secrecy by hiding claims from unauthorized parties.

Failing to distinguish between signed and encrypted tokens leads to frequent implementation mistakes, such as placing sensitive user secrets into a standard signed JWT under the false impression that base64 encoding provides data concealment.

The Standard Implementation: Structure and Worked Example of a Signed JWT

In its compact serialization format, a signed JWT consists of three distinct components concatenated into a single string separated by periods: Header.Payload.Signature (represented structurally as xxxxx.yyyyy.zzzzz).

1. The Header

The header contains metadata describing the token itself, primarily specifying the token type and the cryptographic algorithm used to secure it. Standard header parameters include:

• typ: The token type, which is set to "JWT".
• alg: The cryptographic algorithm used for generating the signature, such as symmetric HMAC variants like HS256, or asymmetric public/private key algorithms like RS256 or ES256.
• kid: An optional key identifier specifying which key should be used to verify the signature.

2. The Payload (Claims)

The payload contains the core claims—statements regarding an entity (typically the user) and contextual metadata. The specification establishes standard reserved claim names:

• iss (Issuer): Identifies the entity that issued the token.
• sub (Subject): The subject or principal identifier represented by the token.
• aud (Audience): The intended recipient or system that should process the token.
• exp (Expiration Time): The Unix timestamp at or after which the token must not be accepted.
• nbf (Not Before): The Unix timestamp before which the token must not be processed.
• iat (Issued At): The Unix timestamp recording when the token was created.

In addition to standard claims, systems can embed custom business attributes into the payload, such as user roles or permission scopes.

3. The Signature

The signature cryptographically validates the token’s integrity. It is computed by taking the Base64URL-encoded header, joining it with a period to the Base64URL-encoded payload, and running that string through the designated algorithm using a secret key or private signing key.

HMACSHA256(
 base64UrlEncode(header) + "." + base64UrlEncode(payload),
 secret
)

Worked Example: Manual Step-by-Step Generation

To observe how the three parts interact, consider a scenario where an identity service issues a signed token for an internal application.

Step 1: Formulate the Header JSON

We specify the HMAC-SHA256 algorithm and mark the type as a JWT:

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

Encoding this raw JSON string into Base64URL produces:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9

Step 2: Formulate the Payload JSON

We define a subject identifier, user role, an issuance timestamp, and an expiration timestamp:

{
 "sub": "usr_8492041",
 "role": "editor",
 "iat": 1735689600,
 "exp": 1735693200
}

Encoding this payload JSON string into Base64URL produces:

eyJzdWIiOiJ1c3JfODQ5MjA0MSIsInJvbGUiOiJlZGl0b3IiLCJpYXQiOjE3MzU2ODk2MDAsImV4cCI6MTczNTY5MzIwMH0

Step 3: Combine and Compute the Signature

We concatenate the encoded header and payload with a period delimiter to establish the signature input:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJ1c3JfODQ5MjA0MSIsInJvbGUiOiJlZGl0b3IiLCJpYXQiOjE3MzU2ODk2MDAsImV4cCI6MTczNTY5MzIwMH0

Using a secure symmetric key string with a length of at least 256 bits, the HMAC-SHA256 algorithm hashes the input string. This generates the third Base64URL component:

7mP8kLw1N9qZxT4vR2yU0oAeCw5IjMnKqHsFvEdG_bA

Step 4: Final Assembled Token

Concatenating all three components yields the compact token transmitted in web requests:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJ1c3JfODQ5MjA0MSIsInJvbGUiOiJlZGl0b3IiLCJpYXQiOjE3MzU2ODk2MDAsImV4cCI6MTczNTY5MzIwMH0.7mP8kLw1N9qZxT4vR2yU0oAeCw5IjMnKqHsFvEdG_bA

While calculating and parsing these segments can be done through code, running the raw string through a dedicated JWT Decoder allows you to inspect the unencrypted header and payload objects instantly without manually converting Base64URL strings.

Alternative Contexts: Which Is Better, OAuth or JWT?

A frequent question in identity architecture is whether OAuth is better than JWT. Asking whether OAuth or JWT is better represents a fundamental misunderstanding of identity architecture: OAuth and JWT are not competing alternatives, but complementary technologies that operate on different architectural layers.

The Functional Difference Between Protocol and Token Format

• OAuth (specifically OAuth 2.0): OAuth is a delegation and authorization framework. It specifies communication flows, grant types, endpoints, and architectural interactions that allow a client application to access resources on behalf of a resource owner without exposing user credentials. OAuth does not dictate the physical format or data structure of the tokens issued.
• JWT: A JWT is a data formatting standard (RFC 7519) that defines how claims are structured, serialized, and cryptographically verified as a JSON object.

Because OAuth 2.0 defines the transport and delegation rules while JWT defines an encoding and signature container, modern identity systems frequently use both simultaneously. Under standards such as RFC 9068, OAuth authorization servers issue JWTs as access tokens.

Comparing OAuth to JWT is akin to comparing HTTP to JSON: one is an operational protocol that manages the exchange of information, while the other is the formatted data payload transferred within that process. You do not choose between OAuth and JWT; rather, you choose whether to use JWT as the token format inside an OAuth framework or deploy JWTs independently as stateless tokens within standard client-server authentication flows.

How to Identify Your Token Format and Cryptographic Context

Because tokens can be formatted for different cryptographic standards and operational architectures, you can identify which context your token belongs to by analyzing its physical composition, headers, and transmission medium:

1. Count the Delimiters: Inspect the raw token string for periods (.):

• Two periods (three segments): This indicates standard JWS compact serialization (Header.Payload.Signature). This confirms you are dealing with a standard signed JWT.
• Four periods (five segments): This indicates a JWE compact serialization token (Header.EncryptedKey.InitializationVector.Ciphertext.AuthenticationTag), confirming that the payload is encrypted rather than merely signed.

2. Examine the alg Parameter in the Header: Base64URL-decoding the first segment reveals the header JSON. The value assigned to the alg field tells you the verification method required:

• Symmetric HMAC (HS256, HS384, HS512): Both token creation and signature verification rely on the exact same shared secret string.
• Asymmetric Public/Private Key (RS256, ES256): The issuer creates the signature using a private key, while API gateways and receiving services verify the signature using the issuer’s public key.

3. Assess Transport and Size Constraints: Practical transport mediums dictate where and how the token is used. Cookies typically have a storage ceiling of 4KB, while HTTP header configurations commonly enforce limits around 8KB. If a token carries extensive claim structures that push against these network constraints, architectures often transition from stateless signed JWTs to lightweight reference identifiers.