How to Secure Your API Endpoints Using Custom JWT Payload Claims

JSON Web Tokens (JWT) have become the de facto standard for stateless API authentication. While most developers understand the basic concept of issuing a token upon login and validating it on subsequent requests, many struggle with leveraging JWTs for fine-grained authorization. In this deep dive, we explore how to effectively secure your API endpoints using custom JWT payload claims.

We will dissect the anatomy of a JWT, examine the difference between standard and custom claims, and demonstrate how to implement Role-Based Access Control (RBAC) securely. Furthermore, we will address common validation pitfalls and cryptographic vulnerabilities that can compromise your entire system if left unchecked.

A JWT consists of three parts separated by dots: Header.Payload.Signature.

• Header: Contains metadata about the token, typically the type (JWT) and the signing algorithm (e.g., HS256 or RS256).
• Payload: Contains the claims, which are statements about an entity (typically, the user) and additional data.
• Signature: Used to verify that the sender of the JWT is who it says it is and to ensure that the message wasn't changed along the way.

For example, a typical header looks like this:

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

Because the payload is merely Base64Url encoded (not encrypted), anyone who intercepts the token can read its contents. Therefore, sensitive information such as passwords or personal identification numbers must never be stored in the payload.

The JWT specification defines a set of standard (or registered) claims, which are not mandatory but recommended to provide a set of useful, interoperable claims. These include:

• iss (Issuer): Identifies the principal that issued the JWT.
• sub (Subject): Identifies the principal that is the subject of the JWT.
• aud (Audience): Identifies the recipients that the JWT is intended for.
• exp (Expiration Time): Identifies the expiration time on or after which the JWT MUST NOT be accepted for processing.

Custom claims, on the other hand, are defined by the application. They can be divided into public claims (defined by URI to avoid collisions) and private claims (custom tailored to your specific application architecture). Private claims are incredibly useful for embedding organizational context directly into the token.

{
  "sub": "1234567890",
  "name": "John Doe",
  "role": "admin",
  "org_id": "org_abc123",
  "permissions": ["read:users", "write:users"]
}

Role-Based Access Control (RBAC) restricts system access to authorized users. By embedding roles and permissions directly into custom JWT claims, you eliminate the need for the API server to perform a database lookup on every request to determine the user's privileges.

Consider an API endpoint POST /api/v1/users. The middleware validating the incoming request can simply decode the JWT, verify the signature, and inspect the custom permissions claim. If the array includes write:users, the request proceeds; otherwise, a 403 Forbidden response is returned.

This approach pushes authorization logic to the edge, significantly reducing database load. However, it requires careful management of token expiration, as changes to a user's permissions in the database won't reflect in their current session until they obtain a new token.

One of the most common mistakes developers make is implicitly trusting the payload without rigorously verifying the signature and standard claims. A robust validation strategy must ensure:

1. The signature perfectly matches the payload and header.
2. The exp (Expiration) claim is checked, and the token is strictly rejected if expired.
3. The iss (Issuer) matches the expected authentication server.
4. The aud (Audience) corresponds to the specific API receiving the token.

Failing to validate the audience (aud) can lead to Confused Deputy attacks, where a token issued for a low-privilege service is intercepted and maliciously forwarded to a high-privilege service.

The JWT specification includes a catastrophic design flaw: it allows the algorithm header (alg) to be set to "none". If an API library naïvely trusts the header without enforcing an algorithm whitelist, an attacker can simply modify the payload, set "alg": "none", and remove the signature.

The flawed library will parse the header, see that no signature verification is required, and accept the maliciously forged token as valid. To prevent this, your validation logic must explicitly demand a secure algorithm (e.g., RS256) and reject any token utilizing the none algorithm.

// Vulnerable approach
jwt.verify(token, publicKey);

// Secure approach
jwt.verify(token, publicKey, { algorithms: ['RS256'] });

Because JWTs are stateless, they cannot easily be revoked. If a token is stolen, the attacker has unrestricted access until the token naturally expires. Therefore, access tokens must be incredibly short-lived (e.g., 5 to 15 minutes).

To maintain a seamless user experience, clients use a longer-lived Refresh Token to request new access tokens in the background. Modern security standards mandate Refresh Token Rotation: every time a refresh token is used, it is invalidated and a new one is issued. If an attacker steals a refresh token and uses it, the server will detect the reuse of a rotated token and immediately revoke the entire token family, neutralizing the breach.

When using asymmetric cryptography (like RSA or ECDSA), the authorization server signs the token with a private key, and the resource server verifies it with a public key. Hardcoding public keys is an anti-pattern.

Instead, use a JSON Web Key Set (JWKS) endpoint. The API fetches the public keys dynamically from the auth server's /.well-known/jwks.json endpoint. The JWT header includes a kid (Key ID), telling the API exactly which key in the JWKS to use for verification. This enables zero-downtime key rotation: the auth server simply publishes a new public key to the JWKS and begins signing new tokens with the corresponding private key.

To debug complex tokens and inspect custom claims, headers, and signatures during development, our JWT Decoder tool provides instant, client-side parsing without ever transmitting your sensitive tokens over the network.